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.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.
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
| Value | Description |
|---|---|
low | Background or nice-to-have work. |
medium | Standard delivery (default). |
high | Important delivery with a near-term deadline. |
critical | Blocking or time-sensitive — requires immediate attention. |
Approval Status
| Value | Description |
|---|---|
pending | Submitted and awaiting a decision. |
approved | Approved — tasks may now be created. |
rejected | Declined; rejected_reason contains the explanation. |
escalated | Escalated to a senior approver. |
cancelled | Withdrawn before a decision was reached. |
needs_clarification | Approver has requested more information. |
Project Status
| Value | Description |
|---|---|
draft | Created but not yet submitted for approval. |
pending_approval | Submitted and in the approval queue. |
approved | Approved by management. |
active | Actively in execution. |
on_hold | Temporarily paused. |
completed | All tasks done and project closed. |
rejected | Not approved. |
archived | Soft-deleted; excluded from default listings. |
Task Status
| Value | Description |
|---|---|
created | Task created and awaiting assignment acknowledgement. |
approved | Approved and ready to be started. |
in_progress | Assignee is actively working on it. |
blocked | Progress is blocked; blocked_reason is set. |
completed | Assignee has marked it done. |
reviewed | Manager has reviewed and signed off. |
reopened | Sent back for rework after review. |
archived | Soft-deleted; excluded from default listings. |
Task Completion Request Status
| Value | Description |
|---|---|
pending | Request submitted, awaiting manager review. |
approved | Approved — task is marked complete. |
rejected | Rejected — task remains open. |
cancelled | Cancelled before review. |
superseded | Replaced 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
Filter by approval status:
pending, approved, rejected, escalated, cancelled, needs_clarification.Filter by project lifecycle status:
draft, pending_approval, approved, active, on_hold, completed, rejected, archived.Return only projects created by this user UUID.
Return only projects assigned to this manager UUID.
Include archived projects. Default:
false.Response Fields
Array of ProjectRead objects.
Example
POST /projects
Submit a new project request for management approval. The project enters apending_approval state until a manager or admin acts on it.
Auth: Any authenticated user.
Request Body
Project name. 1–255 characters.
Detailed project description.
Urgency level:
low, medium (default), high, or critical.Target completion date in
YYYY-MM-DD format.UUID of the manager who should approve this project. Optional for admins.
Response Fields
Returns the createdProjectRead with HTTP 201.
Example
GET /projects/task-eligible
Return only the projects that are eligible for task creation — that is, projects withapproval_status: "approved" — scoped to what the caller can see.
Auth: Any authenticated user.
Response Fields
Returns an array ofProjectRead objects.
Example
GET /projects/
Retrieve a single project by its UUID. Auth: Any authenticated user (RBAC-scoped).Path Parameters
UUID of the project.
Response Fields
Returns a singleProjectRead object.
Example
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
UUID of the project to update.
Request Body
Updated project name. 1–255 characters.
Updated project description.
Updated priority:
low, medium, high, or critical.Updated target completion date in
YYYY-MM-DD format.Updated lifecycle status (admin/manager only).
UUID of the new managing approver.
Response Fields
Returns the updatedProjectRead object.
Example
PATCH /projects//archive
Soft-delete a project by archiving it. Archived projects are excluded from default listings unlessinclude_archived=true is passed.
Auth: Any authenticated user (RBAC-enforced).
Path Parameters
UUID of the project to archive.
Response Fields
Returns the updatedProjectRead object with project_status: "archived".
Example
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
UUID of the project to decide on.
Request Body
The outcome. Must be a valid
ApprovalStatus value: approved, rejected, pending, escalated, cancelled, or needs_clarification.Optional explanation. Strongly recommended when
decision is rejected.Response Fields
Returns the updatedProjectRead with approval_status reflecting the decision.
Example
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
Return only tasks belonging to this project.
Return only tasks assigned to this user UUID.
Filter by task status. Query parameter name is
status. Values: created, approved, in_progress, blocked, completed, reviewed, reopened, archived.Include archived tasks in results. Default:
false.Response Fields
Array of TaskRead objects.
Example
POST /tasks
Create a new task within an approved project and assign it to an employee. The parent project must haveapproval_status: "approved".
Auth: Any authenticated user (RBAC-enforced; typically Manager or Admin).
Request Body
UUID of the approved project this task belongs to.
UUID of the employee to assign this task to.
Task name. 1–255 characters.
Detailed description of what needs to be done.
Task urgency:
low, medium (default), high, or critical.Target completion date in
YYYY-MM-DD format.UUID of a parent task to create this as a subtask.
Response Fields
Returns the createdTaskRead with HTTP 201.
Example
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
Filter by request status:
pending, approved, rejected, cancelled, superseded.Response Fields
Array of TaskCompletionRequestRead objects.
Example
GET /tasks/completion-requests/
Retrieve a single task completion request by its UUID. Auth: Any authenticated user (RBAC-scoped).Path Parameters
UUID of the completion request.
Response Fields
Returns a singleTaskCompletionRequestRead object.
Example
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
UUID of the completion request to approve.
Request Body
Optional review comment. Max 2000 characters.
Response Fields
Returns the updatedTaskCompletionRequestRead with status: "approved".
Example
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
UUID of the completion request to reject.
Request Body
Reason for rejection. Required. Max 2000 characters.
Response Fields
Returns the updatedTaskCompletionRequestRead with status: "rejected".
Example
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.Filter tasks assigned to a specific employee.
Filter tasks belonging to a specific project.
Filter by task status value.
Filter by priority:
low, medium, high, critical.Filter by active timer state:
running, paused, or not_started.Filter tasks with
due_date on or after this date (YYYY-MM-DD).Filter tasks with
due_date on or before this date (YYYY-MM-DD).Maximum number of tasks to return. Default:
50.Pagination offset. Default:
0.Response Fields
Organisation-wide aggregate statistics.
Total number of tasks matching the applied filters.
Paginated list of task objects enriched with
timer_state, timer_duration_seconds, and timer_pause_reason.List of currently active or paused timer sessions with employee and duration details.
Example
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
UUID of the task.
Response Fields
Returns a singleTaskRead object.
Example
PATCH /tasks/
Update one or more fields of an existing task, including advancing the status through the lifecycle. Employees can move tasks betweenapproved, 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
UUID of the task to update.
Request Body
Updated task name. 1–255 characters.
Updated task description.
Reassign task to a different project.
Re-assign task to a different employee UUID.
Move task under a different parent task.
Updated priority:
low, medium, high, or critical.Updated due date in
YYYY-MM-DD format.New task status. Valid values and transitions depend on the caller’s role.
Required when setting
status to blocked. Explain the blocker.Response Fields
Returns the updatedTaskRead object.
Example — Move to in_progress
POST /tasks//complete
Mark a task as completed. Forintern 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
UUID of the task to complete.
Response Fields
Returns the updatedTaskRead object. For interns, status remains unchanged until the completion request is approved.
Example
PATCH /tasks//archive
Soft-delete a task by archiving it. Archived tasks are excluded from default listings unlessinclude_archived=true is passed.
Auth: Any authenticated user (RBAC-enforced).
Path Parameters
UUID of the task to archive.
Response Fields
Returns the updatedTaskRead object with status: "archived".
Example
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; typicallyintern).
Path Parameters
UUID of the task the intern is requesting to close.
Request Body
Optional note describing what was done. Max 2000 characters.
Response Fields
Returns the createdTaskCompletionRequestRead object with HTTP 201.
Example
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
UUID of the task to score.
Request Body
Complexity score from
1 (trivial) to 10 (extremely complex).Estimated effort in minutes. Must be greater than 0.
Response Fields
Returns the updatedTaskRead with complexity_level and expected_duration_minutes set.
Example
GET /tasks//subtasks
List all direct subtasks of the specified task. Auth: Any authenticated user (RBAC-scoped).Path Parameters
UUID of the parent task.
Response Fields
Returns an array ofTaskRead objects.
Example
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
UUID of the task to comment on.
Request Body
Comment text. Minimum 1 character.
Response Fields
Unique comment identifier.
UUID of the parent task.
UUID of the comment author.
Comment text.
Creation timestamp.
Last update timestamp.
TaskCommentRead with HTTP 201.
Example
GET /tasks//comments
List all comments on a task in chronological order. Auth: Any authenticated user (RBAC-scoped).Path Parameters
UUID of the task.
Response Fields
Returns an array ofTaskCommentRead objects.
Example
Standard Error Response
400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict.