API Reference¶
Auto-generated from the FastAPI OpenAPI schema. Do not edit by hand —
run make docs-api to regenerate. For usage examples and authentication
setup, see the API Guide.
A running server also exposes interactive docs at /docs (Swagger UI)
and /redoc (ReDoc).
Other¶
GET /¶
Root
Root endpoint.
Responses: 200
GET /health¶
Health
Health check endpoint.
Responses: 200
analytics¶
GET /api/v1/statistics¶
Get Statistics
Get task statistics for a time period.
Args: controller: Analytics controller dependency period: Time period (all, 7d, 30d)
Returns: Task statistics including completion, time, estimation, deadline, and trends
Raises: HTTPException: 400 if period is invalid
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
period |
query | string | no | Time period: all, 7d, or 30d |
Responses: 200, 422
GET /api/v1/tags/statistics¶
Get Tag Statistics
Get tag usage statistics.
Args: controller: Query controller dependency
Returns: Tag statistics including count and completion rate per tag
Responses: 200
GET /api/v1/gantt¶
Get Gantt Chart
Get Gantt chart data with workload calculations.
Returns the shared task list plus the Gantt overlay (daily hours, workload, holidays); clients join them by task id.
Args: controller: Query controller dependency holiday_checker: Holiday checker dependency include_archived: Include archived tasks status_filter: Filter by task status tags: Filter by tags (OR logic) start_date: Chart start date end_date: Chart end date sort: Sort field name reverse: Reverse sort order
Returns: Task list with the Gantt overlay populated
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
all |
query | boolean | no | Include archived tasks |
status |
query | string | null | no | Filter by status |
tags |
query | array | null | no | Filter by tags (OR logic) |
start_date |
query | string | null | no | Chart start date (ISO format) |
end_date |
query | string | null | no | Chart end date (ISO format) |
sort |
query | string | no | Sort field |
reverse |
query | boolean | no | Reverse sort order |
Responses: 200, 422
POST /api/v1/optimize¶
Optimize Schedule
Optimize task schedules using specified algorithm.
Args: request: Optimization parameters controller: Analytics controller dependency broadcaster: Event broadcaster dependency time_provider: Time provider dependency client_name: Authenticated client name (used for broadcast exclusion)
Returns: Optimization results with summary and failures
Raises: HTTPException: 400 if validation fails
Request body: OptimizeScheduleRequest
Responses: 200, 422
GET /api/v1/algorithms¶
List Algorithms
List available optimization algorithms.
Args: controller: Query controller dependency
Returns: List of algorithms with name, display name, and description
Responses: 200
audit¶
GET /api/v1/audit-logs¶
List Audit Logs
List audit logs with optional filtering.
Args: controller: Audit log controller dependency client_filter: Filter by client name (e.g., "claude-code") operation: Filter by operation type (e.g., "create_task", "complete_task") resource_type: Filter by resource type (e.g., "task", "schedule") resource_id: Filter by resource ID (e.g., task ID) success: Filter by success status start_date: Filter logs after this datetime (ISO format) end_date: Filter logs before this datetime (ISO format) limit: Maximum number of logs to return (1-10000, default 100) offset: Number of logs to skip for pagination (default 0)
Returns: AuditLogListResponse with logs and pagination info
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
client |
query | string | null | no | Filter by client name |
operation |
query | string | null | no | Filter by operation type |
resource_type |
query | string | null | no | Filter by resource type |
resource_id |
query | integer | null | no | Filter by resource ID |
success |
query | boolean | null | no | Filter by success status |
start_date |
query | string | null | no | Filter by start datetime (ISO format) |
end_date |
query | string | null | no | Filter by end datetime (ISO format) |
limit |
query | integer | no | Maximum number of logs to return |
offset |
query | integer | no | Number of logs to skip |
Responses: 200, 422
GET /api/v1/audit-logs/{log_id}¶
Get Audit Log
Get a single audit log entry by ID.
Args: log_id: Audit log ID controller: Audit log controller dependency
Returns: AuditLogResponse if found
Raises: HTTPException: 404 if audit log not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
log_id |
path | integer | yes |
Responses: 200, 422
backup¶
GET /api/v1/backup¶
Backup
Stream a consistent physical snapshot of the database as a .db file.
Responses: 200
POST /api/v1/restore¶
Restore
Stage an uploaded .db snapshot to be applied on the next server restart.
Responses: 200, 422
bulk¶
POST /api/v1/tasks/bulk/start¶
Start multiple tasks
Request body: BulkTaskIdsRequest
Responses: 200, 422
POST /api/v1/tasks/bulk/complete¶
Complete multiple tasks
Request body: BulkTaskIdsRequest
Responses: 200, 422
POST /api/v1/tasks/bulk/pause¶
Pause multiple tasks
Request body: BulkTaskIdsRequest
Responses: 200, 422
POST /api/v1/tasks/bulk/cancel¶
Cancel multiple tasks
Request body: BulkTaskIdsRequest
Responses: 200, 422
POST /api/v1/tasks/bulk/reopen¶
Reopen multiple tasks
Request body: BulkTaskIdsRequest
Responses: 200, 422
POST /api/v1/tasks/bulk/archive¶
Archive multiple tasks
Request body: BulkTaskIdsRequest
Responses: 200, 422
POST /api/v1/tasks/bulk/restore¶
Restore multiple tasks
Request body: BulkTaskIdsRequest
Responses: 200, 422
POST /api/v1/tasks/bulk/delete¶
Delete multiple tasks permanently
Request body: BulkTaskIdsRequest
Responses: 200, 422
lifecycle¶
POST /api/v1/tasks/{task_id}/start¶
Endpoint
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
POST /api/v1/tasks/{task_id}/complete¶
Endpoint
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
POST /api/v1/tasks/{task_id}/pause¶
Endpoint
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
POST /api/v1/tasks/{task_id}/cancel¶
Endpoint
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
POST /api/v1/tasks/{task_id}/reopen¶
Endpoint
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
POST /api/v1/tasks/{task_id}/fix-actual¶
Fix Actual Times
Fix actual start/end timestamps and/or duration for a task.
Used to correct timestamps after the fact, for historical accuracy. Past dates are allowed since these are historical records.
Args: task_id: Task ID request: Fix actual times request with optional start/end/duration values controller: Lifecycle controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Updated task data with corrected timestamps/duration
Raises: HTTPException: 404 if task not found, 400 if validation fails
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Request body: FixActualTimesRequest
Responses: 200, 422
notes¶
GET /api/v1/tasks/{task_id}/notes¶
Get Task Notes
Get task notes.
Args: task_id: Task ID controller: Notes controller dependency
Returns: Notes content and metadata
Raises: HTTPException: 404 if task not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
PUT /api/v1/tasks/{task_id}/notes¶
Update Task Notes
Update task notes.
Args: task_id: Task ID request: Notes content controller: Notes controller dependency broadcaster: Event broadcaster dependency client_name: Authenticated client name (used for broadcast exclusion)
Returns: Updated notes content and metadata
Raises: HTTPException: 404 if task not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Request body: UpdateNotesRequest
Responses: 200, 422
DELETE /api/v1/tasks/{task_id}/notes¶
Delete Task Notes
Delete task notes.
Args: task_id: Task ID controller: Notes controller dependency broadcaster: Event broadcaster dependency client_name: Authenticated client name (used for broadcast exclusion)
Raises: HTTPException: 404 if task not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 204, 422
relationships¶
POST /api/v1/tasks/{task_id}/dependencies¶
Add Dependency
Add a dependency to a task.
Args: task_id: Task ID that will depend on another task request: Dependency data (ID of task to depend on) controller: Relationship controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Updated task data with new dependency
Raises: HTTPException: 404 if task not found, 400 if validation fails (e.g., circular dependency)
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Request body: AddDependencyRequest
Responses: 200, 422
DELETE /api/v1/tasks/{task_id}/dependencies/{depends_on_id}¶
Remove Dependency
Remove a dependency from a task.
Args: task_id: Task ID depends_on_id: ID of dependency to remove controller: Relationship controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Updated task data without the dependency
Raises: HTTPException: 404 if task not found, 400 if validation fails
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes | |
depends_on_id |
path | integer | yes |
Responses: 200, 422
PUT /api/v1/tasks/{task_id}/tags¶
Set Task Tags
Set task tags (replaces existing tags).
Args: task_id: Task ID request: New tags list controller: Relationship controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Updated task data with new tags
Raises: HTTPException: 404 if task not found, 400 if validation fails
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Request body: SetTaskTagsRequest
Responses: 200, 422
tags¶
DELETE /api/v1/tags/{tag_name}¶
Delete Tag
Delete a tag from the system.
Removes the tag and all its associations with tasks.
Args: tag_name: Name of the tag to delete controller: Relationship controller dependency audit_controller: Audit log controller dependency client_name: Authenticated client name
Returns: Deleted tag name and number of affected tasks
Raises: HTTPException: 404 if tag not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
tag_name |
path | string | yes |
Responses: 200, 422
tasks¶
POST /api/v1/tasks¶
Create Task
Create a new task.
Args: request: Task creation data controller: CRUD controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Created task data
Raises: HTTPException: 400 if validation fails
Request body: CreateTaskRequest
Responses: 201, 422
GET /api/v1/tasks¶
List Tasks
List tasks with optional filtering and sorting.
Args: controller: Query controller dependency holiday_checker: Holiday checker dependency include_archived: Include archived tasks status_filter: Filter by task status tags: Filter by tags (OR logic) start_date: Filter by start date (ISO format) end_date: Filter by end date (ISO format) sort: Sort field name reverse: Reverse sort order include_gantt: Include Gantt chart data gantt_start_date: Gantt chart start date (ISO format) gantt_end_date: Gantt chart end date (ISO format)
Returns: List of tasks with metadata, optionally including Gantt data
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
all |
query | boolean | no | Include archived tasks |
status |
query | string | null | no | Filter by status |
tags |
query | array | null | no | Filter by tags (OR logic) |
start_date |
query | string | null | no | Filter by start date |
end_date |
query | string | null | no | Filter by end date |
sort |
query | string | no | Sort field |
reverse |
query | boolean | no | Reverse sort order |
include_gantt |
query | boolean | no | Include Gantt chart data in response |
gantt_start_date |
query | string | null | no | Gantt chart start date (ISO format) |
gantt_end_date |
query | string | null | no | Gantt chart end date (ISO format) |
Responses: 200, 422
GET /api/v1/tasks/by-ids¶
Get Tasks By Ids
Retrieve multiple tasks by ID in a single batched request.
Fetches all requested tasks with one query, avoiding per-id round trips. Missing ids are omitted from the response; output order follows the input id order.
Args: controller: Query controller dependency ids: Task IDs to retrieve
Returns: List of the found tasks with metadata
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
ids |
query | array | yes | Task IDs to retrieve in a single request |
Responses: 200, 422
GET /api/v1/tasks/executable¶
Get Executable Tasks
List executable tasks ranked by what to work on next.
Args: controller: Query controller dependency tags: Optional tag filter limit: Maximum number of tasks to return
Returns: Ranked tasks with the ranking basis used
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
tags |
query | array | null | no | Filter by tags (OR logic) |
limit |
query | integer | no | Maximum tasks to return |
Responses: 200, 422
GET /api/v1/tasks/{task_id}¶
Get Task
Get task details by ID.
Args: task_id: Task ID controller: Query controller dependency
Returns: Task detail data including notes
Raises: HTTPException: 404 if task not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
PATCH /api/v1/tasks/{task_id}¶
Update Task
Update task fields.
Args: task_id: Task ID request: Fields to update (only provided fields are updated) controller: CRUD controller dependency query_controller: Query controller dependency (for fetching old values) broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Updated task data
Raises: HTTPException: 404 if task not found, 400 if validation fails
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Request body: UpdateTaskRequest
Responses: 200, 422
DELETE /api/v1/tasks/{task_id}¶
Delete Task
Permanently delete a task.
Args: task_id: Task ID controller: CRUD controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Deleted task data
Raises: HTTPException: 404 if task not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
POST /api/v1/tasks/{task_id}/archive¶
Archive Task
Archive (soft delete) a task.
Args: task_id: Task ID controller: CRUD controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Archived task data
Raises: HTTPException: 404 if task not found
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422
POST /api/v1/tasks/{task_id}/restore¶
Restore Task
Restore an archived task.
Args: task_id: Task ID controller: CRUD controller dependency broadcaster: Event broadcaster dependency audit_controller: Audit log controller dependency client_name: Authenticated client name (for broadcast payload)
Returns: Restored task data
Raises: HTTPException: 404 if task not found, 400 if not archived
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
task_id |
path | integer | yes |
Responses: 200, 422