API Reference
Interactive reference for the OpenTask REST API, auto-generated from the OpenAPI 3.1 specification.
REST API for OpenTask, a self-hosted task management application.
Authentication
All endpoints (except /api/health and /api/openapi) require authentication
via one of:
- Bearer token —
Authorization: Bearer <token>header - Reverse proxy header — configured via
OPENTASK_PROXY_AUTH_HEADERenv var - Session cookie — set by the web UI login flow
Bearer tokens are created via POST /api/tokens or the db:create-token CLI command.
Response format
Success: { "data": { ... } }
Error: { "error": "message", "code": "ERROR_CODE", "details": { ... } }
Servers
List tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Filter by completion status (default false)
Filter by label name
Search in title and notes
2000Responses
List of tasks
Samples
Create task
Send a raw title string for AI enrichment, or provide structured fields
to bypass enrichment. AI enrichment triggers when only title is provided
(no due_at, priority=0, no labels, no rrule).
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created task
Samples
Get task
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Task details
Samples
Delete task (soft delete to trash)
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Trashed task
Samples
Update task
PATCH semantics — only fields present in the body are updated.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Updated task with change metadata
Samples
Mark task done
For recurring tasks, advances due_at to the next occurrence.
For one-off tasks, sets done=true and archives.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Completed task
Samples
Mark task undone (reopen)
Only works for one-off tasks. For recurring tasks, use undo.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Reopened task
Samples
Snooze task
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Snoozed task
Samples
Restore task from trash
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Restored task
Samples
Retry AI enrichment
Re-runs AI enrichment using the original_title.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Task queued for reprocessing
Samples
Mark multiple tasks done
Snooze multiple tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Snooze all overdue tasks
Snoozes all overdue P0-P3 tasks. P4 (Urgent) tasks are always excluded.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Edit multiple tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Bulk operation result
Samples
Soft-delete multiple tasks
List projects
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
List of projects with task counts
Samples
Create project
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created project
Samples
Get project
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Project details
Samples
Delete project
Update project
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Updated project
Samples
List trashed tasks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
200Responses
Trashed tasks
Samples
Empty trash (permanent delete)
Permanently deletes all trashed tasks. Cannot be undone.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Number of tasks permanently deleted
Samples
Export user data
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
"json""csv""json"Required for CSV format. Each table is a separate file.
"tasks""projects"Responses
Exported data
Samples
List webhooks
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
User's webhooks (secrets excluded)
Samples
Create webhook
Creates a webhook with an auto-generated HMAC secret.
The secret is returned in this response only — store it securely.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created webhook with secret (shown once)
Samples
Delete webhook
Update webhook
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Updated webhook (secret excluded)
Samples
List recent webhook deliveries
Returns the last 50 delivery attempts for debugging.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
Delivery history
Samples
List API tokens
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Responses
API tokens (previews only, not full tokens)
Samples
Create API token
Creates a new API token. The full token is returned in this response only.
Tokens are stored as SHA-256 hashes — the raw token cannot be retrieved later.
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Request Body
Responses
Created token (shown once)
Samples
Revoke API token
Get user statistics
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Start date for daily stats range (YYYY-MM-DD)
"date"End date for daily stats range (YYYY-MM-DD)
"date"Responses
Stats summary or daily stats for date range
Samples
Query completion history
Authorizations
API token created via POST /api/tokens or the db:create-token CLI command
Parameters
Query Parameters
Filter by completion date (YYYY-MM-DD)
"date"Responses
Completion records