Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Paramount-Intelligence/HR_Monitoring_System/llms.txt

Use this file to discover all available pages before exploring further.

The Projects and Tasks APIs work in tandem to model the organisation’s work breakdown structure. Projects act as containers that require management approval before tasks can be created under them. Once a project is approved, managers and admins can create tasks, assign them to employees, advance them through a defined status lifecycle, and set complexity scores for workload analysis. Interns submit completion requests that must be approved by a manager before a task is closed.
Project endpoints are prefixed /api/v1/projects; task endpoints are prefixed /api/v1/tasks. Both require an Authorization: Bearer <token> header.

Enum Reference

Project Priority

ValueDescription
lowBackground or nice-to-have work.
mediumStandard delivery (default).
highImportant delivery with a near-term deadline.
criticalBlocking or time-sensitive — requires immediate attention.

Approval Status

ValueDescription
pendingSubmitted and awaiting a decision.
approvedApproved — tasks may now be created.
rejectedDeclined; rejected_reason contains the explanation.
escalatedEscalated to a senior approver.
cancelledWithdrawn before a decision was reached.
needs_clarificationApprover has requested more information.

Project Status

ValueDescription
draftCreated but not yet submitted for approval.
pending_approvalSubmitted and in the approval queue.
approvedApproved by management.
activeActively in execution.
on_holdTemporarily paused.
completedAll tasks done and project closed.
rejectedNot approved.
archivedSoft-deleted; excluded from default listings.

Task Status

ValueDescription
createdTask created and awaiting assignment acknowledgement.
approvedApproved and ready to be started.
in_progressAssignee is actively working on it.
blockedProgress is blocked; blocked_reason is set.
completedAssignee has marked it done.
reviewedManager has reviewed and signed off.
reopenedSent back for rework after review.
archivedSoft-deleted; excluded from default listings.

Task Completion Request Status

ValueDescription
pendingRequest submitted, awaiting manager review.
approvedApproved — task is marked complete.
rejectedRejected — task remains open.
cancelledCancelled before review.
supersededReplaced by a newer request.

GET /projects

List projects visible to the authenticated caller. Admins and HR see all projects; Managers see projects they own or manage; Employees see projects they are involved with via tasks. Auth: Any authenticated user. Results are RBAC-scoped.

Query Parameters

approval_status
string
Filter by approval status: pending, approved, rejected, escalated, cancelled, needs_clarification.
project_status
string
Filter by project lifecycle status: draft, pending_approval, approved, active, on_hold, completed, rejected, archived.
owner_id
uuid
Return only projects created by this user UUID.
manager_id
uuid
Return only projects assigned to this manager UUID.
include_archived
boolean
Include archived projects. Default: false.

Response Fields

[]
array
Array of ProjectRead objects.
Example
curl -X GET "https://api.example.com/api/v1/projects?approval_status=approved&project_status=active" \
  -H "Authorization: Bearer <token>"

POST /projects

Submit a new project request for management approval. The project enters a pending_approval state until a manager or admin acts on it. Auth: Any authenticated user.

Request Body

title
string
required
Project name. 1–255 characters.
description
string
Detailed project description.
priority
string
Urgency level: low, medium (default), high, or critical.
due_date
string
Target completion date in YYYY-MM-DD format.
manager_id
uuid
UUID of the manager who should approve this project. Optional for admins.

Response Fields

Returns the created ProjectRead with HTTP 201.
Example
curl -X POST "https://api.example.com/api/v1/projects" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Portal Redesign Q3",
    "description": "Full UI/UX overhaul of the self-service customer portal.",
    "priority": "high",
    "due_date": "2024-09-30",
    "manager_id": "a1b2c3d4-0000-0000-0000-000000000001"
  }'

GET /projects/task-eligible

Return only the projects that are eligible for task creation — that is, projects with approval_status: "approved" — scoped to what the caller can see. Auth: Any authenticated user.

Response Fields

Returns an array of ProjectRead objects.
Example
curl -X GET "https://api.example.com/api/v1/projects/task-eligible" \
  -H "Authorization: Bearer <token>"

GET /projects/

Retrieve a single project by its UUID. Auth: Any authenticated user (RBAC-scoped).

Path Parameters

project_id
uuid
required
UUID of the project.

Response Fields

Returns a single ProjectRead object.
Example
curl -X GET "https://api.example.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>"

PATCH /projects/

Update a project’s metadata. Permitted fields depend on the caller’s role and the project’s current status. Auth: Any authenticated user (RBAC-enforced).

Path Parameters

project_id
uuid
required
UUID of the project to update.

Request Body

title
string
Updated project name. 1–255 characters.
description
string
Updated project description.
priority
string
Updated priority: low, medium, high, or critical.
due_date
string
Updated target completion date in YYYY-MM-DD format.
project_status
string
Updated lifecycle status (admin/manager only).
manager_id
uuid
UUID of the new managing approver.

Response Fields

Returns the updated ProjectRead object.
Example
curl -X PATCH "https://api.example.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "critical",
    "due_date": "2024-08-31"
  }'

PATCH /projects//archive

Soft-delete a project by archiving it. Archived projects are excluded from default listings unless include_archived=true is passed. Auth: Any authenticated user (RBAC-enforced).

Path Parameters

project_id
uuid
required
UUID of the project to archive.

Response Fields

Returns the updated ProjectRead object with project_status: "archived".
Example
curl -X PATCH "https://api.example.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/archive" \
  -H "Authorization: Bearer <token>"

POST /projects//approve

Approve or reject a project that is pending approval. Only the assigned manager or an admin/HR operator may call this endpoint. Auth: Manager (own projects), Admin, or HR Operations.

Path Parameters

project_id
uuid
required
UUID of the project to decide on.

Request Body

decision
string
required
The outcome. Must be a valid ApprovalStatus value: approved, rejected, pending, escalated, cancelled, or needs_clarification.
reason
string
Optional explanation. Strongly recommended when decision is rejected.

Response Fields

Returns the updated ProjectRead with approval_status reflecting the decision.
Once a project is approved, task creation against it becomes unlocked. Use GET /projects/task-eligible to fetch only projects available for task creation.
Example
curl -X POST "https://api.example.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/approve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approved"
  }'

GET /tasks

List tasks visible to the authenticated caller. Results are automatically scoped: employees and interns see only tasks assigned to them; managers see their team’s tasks; admins see all tasks. Auth: Any authenticated user. Results are RBAC-scoped.

Query Parameters

project_id
uuid
Return only tasks belonging to this project.
assigned_to
uuid
Return only tasks assigned to this user UUID.
status
string
Filter by task status. Query parameter name is status. Values: created, approved, in_progress, blocked, completed, reviewed, reopened, archived.
include_archived
boolean
Include archived tasks in results. Default: false.

Response Fields

[]
array
Array of TaskRead objects.
Example
curl -X GET "https://api.example.com/api/v1/tasks?project_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&status=in_progress" \
  -H "Authorization: Bearer <token>"

POST /tasks

Create a new task within an approved project and assign it to an employee. The parent project must have approval_status: "approved". Auth: Any authenticated user (RBAC-enforced; typically Manager or Admin).

Request Body

project_id
uuid
required
UUID of the approved project this task belongs to.
assigned_to
uuid
required
UUID of the employee to assign this task to.
title
string
required
Task name. 1–255 characters.
description
string
Detailed description of what needs to be done.
priority
string
Task urgency: low, medium (default), high, or critical.
due_date
string
Target completion date in YYYY-MM-DD format.
parent_id
uuid
UUID of a parent task to create this as a subtask.

Response Fields

Returns the created TaskRead with HTTP 201.
Example
curl -X POST "https://api.example.com/api/v1/tasks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "assigned_to": "b4c5d6e7-0000-0000-0000-000000000002",
    "title": "Implement OAuth2 login flow",
    "description": "Add Google SSO using OAuth2 PKCE flow.",
    "priority": "high",
    "due_date": "2024-08-15"
  }'

GET /tasks/completion-requests

List task completion requests visible to the authenticated caller. Managers see requests for their team; admins see all; interns see their own requests. Auth: Any authenticated user. Results are RBAC-scoped.

Query Parameters

status
string
Filter by request status: pending, approved, rejected, cancelled, superseded.

Response Fields

[]
array
Array of TaskCompletionRequestRead objects.
Example
curl -X GET "https://api.example.com/api/v1/tasks/completion-requests?status=pending" \
  -H "Authorization: Bearer <token>"

GET /tasks/completion-requests/

Retrieve a single task completion request by its UUID. Auth: Any authenticated user (RBAC-scoped).

Path Parameters

request_id
uuid
required
UUID of the completion request.

Response Fields

Returns a single TaskCompletionRequestRead object.
Example
curl -X GET "https://api.example.com/api/v1/tasks/completion-requests/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>"

POST /tasks/completion-requests//approve

Approve an intern’s task completion request, closing the task as complete. Auth: Manager or Admin (RBAC-enforced).

Path Parameters

request_id
uuid
required
UUID of the completion request to approve.

Request Body

manager_comment
string
Optional review comment. Max 2000 characters.

Response Fields

Returns the updated TaskCompletionRequestRead with status: "approved".
Example
curl -X POST "https://api.example.com/api/v1/tasks/completion-requests/3fa85f64-5717-4562-b3fc-2c963f66afa6/approve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"manager_comment": "Well done — merged and deployed."}'

POST /tasks/completion-requests//reject

Reject an intern’s task completion request, leaving the task open for further work. Auth: Manager or Admin (RBAC-enforced).

Path Parameters

request_id
uuid
required
UUID of the completion request to reject.

Request Body

manager_comment
string
required
Reason for rejection. Required. Max 2000 characters.

Response Fields

Returns the updated TaskCompletionRequestRead with status: "rejected".
Example
curl -X POST "https://api.example.com/api/v1/tasks/completion-requests/3fa85f64-5717-4562-b3fc-2c963f66afa6/reject" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"manager_comment": "Unit tests are failing — please fix before resubmitting."}'

GET /tasks/admin/overview

Admin-only dashboard endpoint that returns aggregate task statistics plus a filterable list of all tasks with live timer state. Used to power the organisation-wide task monitoring view. Auth: admin role required.

Query Parameters

Full-text search across task title and description.
employee_id
uuid
Filter tasks assigned to a specific employee.
project_id
uuid
Filter tasks belonging to a specific project.
status
string
Filter by task status value.
priority
string
Filter by priority: low, medium, high, critical.
timer_state
string
Filter by active timer state: running, paused, or not_started.
start_date
date
Filter tasks with due_date on or after this date (YYYY-MM-DD).
end_date
date
Filter tasks with due_date on or before this date (YYYY-MM-DD).
limit
integer
Maximum number of tasks to return. Default: 50.
offset
integer
Pagination offset. Default: 0.

Response Fields

summary
object
required
Organisation-wide aggregate statistics.
total_count
integer
required
Total number of tasks matching the applied filters.
tasks
array
required
Paginated list of task objects enriched with timer_state, timer_duration_seconds, and timer_pause_reason.
active_work
array
required
List of currently active or paused timer sessions with employee and duration details.
Example
curl -X GET "https://api.example.com/api/v1/tasks/admin/overview?status=in_progress&limit=20" \
  -H "Authorization: Bearer <token>"

GET /tasks/

Retrieve a single task by its UUID, enriched with completion request state and action flags for the caller. Auth: Any authenticated user (RBAC-scoped).

Path Parameters

task_id
uuid
required
UUID of the task.

Response Fields

Returns a single TaskRead object.
Example
curl -X GET "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>"

PATCH /tasks/

Update one or more fields of an existing task, including advancing the status through the lifecycle. Employees can move tasks between approved, in_progress, and blocked; Managers can additionally transition to reviewed or reopened; Admins have unrestricted access. Auth: Any authenticated user. Permitted transitions are RBAC-enforced.

Path Parameters

task_id
uuid
required
UUID of the task to update.

Request Body

title
string
Updated task name. 1–255 characters.
description
string
Updated task description.
project_id
uuid
Reassign task to a different project.
assigned_to
uuid
Re-assign task to a different employee UUID.
parent_id
uuid
Move task under a different parent task.
priority
string
Updated priority: low, medium, high, or critical.
due_date
string
Updated due date in YYYY-MM-DD format.
status
string
New task status. Valid values and transitions depend on the caller’s role.
blocked_reason
string
Required when setting status to blocked. Explain the blocker.

Response Fields

Returns the updated TaskRead object.
Example — Move to in_progress
curl -X PATCH "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress"
  }'

POST /tasks//complete

Mark a task as completed. For intern role users, this creates a completion request that must be approved by a manager rather than closing the task immediately. Auth: Any authenticated user (RBAC-enforced).

Path Parameters

task_id
uuid
required
UUID of the task to complete.

Response Fields

Returns the updated TaskRead object. For interns, status remains unchanged until the completion request is approved.
Example
curl -X POST "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6/complete" \
  -H "Authorization: Bearer <token>"

PATCH /tasks//archive

Soft-delete a task by archiving it. Archived tasks are excluded from default listings unless include_archived=true is passed. Auth: Any authenticated user (RBAC-enforced).

Path Parameters

task_id
uuid
required
UUID of the task to archive.

Response Fields

Returns the updated TaskRead object with status: "archived".
Example
curl -X PATCH "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6/archive" \
  -H "Authorization: Bearer <token>"

POST /tasks//completion-requests

Intern-specific endpoint to submit a completion approval request for a task. The request is routed to the task’s manager for review. Auth: Any authenticated user (RBAC-enforced; typically intern).

Path Parameters

task_id
uuid
required
UUID of the task the intern is requesting to close.

Request Body

request_note
string
Optional note describing what was done. Max 2000 characters.

Response Fields

Returns the created TaskCompletionRequestRead object with HTTP 201.
Example
curl -X POST "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6/completion-requests" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"request_note": "Implemented and tested all acceptance criteria. PR #142 merged."}'

POST /tasks//complexity

Set the complexity level and expected duration for a task. This data feeds into workload analysis and burndown reports. Auth: Manager or Admin (RBAC-enforced).

Path Parameters

task_id
uuid
required
UUID of the task to score.

Request Body

complexity_level
integer
required
Complexity score from 1 (trivial) to 10 (extremely complex).
expected_duration_minutes
integer
required
Estimated effort in minutes. Must be greater than 0.

Response Fields

Returns the updated TaskRead with complexity_level and expected_duration_minutes set.
Calling this endpoint without manager or admin role returns 403 Forbidden.
Example
curl -X POST "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6/complexity" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "complexity_level": 7,
    "expected_duration_minutes": 480
  }'

GET /tasks//subtasks

List all direct subtasks of the specified task. Auth: Any authenticated user (RBAC-scoped).

Path Parameters

task_id
uuid
required
UUID of the parent task.

Response Fields

Returns an array of TaskRead objects.
Example
curl -X GET "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6/subtasks" \
  -H "Authorization: Bearer <token>"

POST /tasks//comments

Add a comment to a task. Comments are visible to all users who can see the task. Auth: Any authenticated user (RBAC-scoped).

Path Parameters

task_id
uuid
required
UUID of the task to comment on.

Request Body

content
string
required
Comment text. Minimum 1 character.

Response Fields

id
uuid
required
Unique comment identifier.
task_id
uuid
required
UUID of the parent task.
user_id
uuid
required
UUID of the comment author.
content
string
required
Comment text.
created_at
datetime
required
Creation timestamp.
updated_at
datetime
required
Last update timestamp.
Returns the created TaskCommentRead with HTTP 201.
Example
curl -X POST "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6/comments" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"content": "Blocked on API credentials — following up with DevOps."}'

GET /tasks//comments

List all comments on a task in chronological order. Auth: Any authenticated user (RBAC-scoped).

Path Parameters

task_id
uuid
required
UUID of the task.

Response Fields

Returns an array of TaskCommentRead objects.
Example
curl -X GET "https://api.example.com/api/v1/tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6/comments" \
  -H "Authorization: Bearer <token>"

Standard Error Response

{
  "detail": "Project not found or you do not have access."
}
Common HTTP status codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict.

Build docs developers (and LLMs) love