Automation

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer $TOKEN

Creating a token

# Docker
docker compose exec opentask tsx scripts/create-token.ts <username> [token-name]

# Bare metal
npm run db:create-token -- <username> [token-name]

The token is printed once. Store it securely — it cannot be retrieved later. Tokens are stored as SHA-256 hashes on the server.

Auth methods

OpenTask checks authentication in this order:

1. Bearer token — For scripts and automation
2. Proxy header — For reverse proxy auth (Authelia, Authentik)
3. Session cookie — For the web UI (managed automatically)

If a Bearer token is present but invalid, the request is rejected immediately — it never falls through to session auth.

Quick Add

Send raw dictated text and let AI enrichment handle the rest:

curl -X POST https://tasks.example.com/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "call the dentist tomorrow morning high priority"}'

AI extracts: clean title, due date, priority, labels, recurrence, project, and notes. The raw input is preserved in original_title for retry if enrichment fails.

See How Enrichment Works for the full list of extracted fields.

Structured Create (Skip AI)

Send structured fields to bypass enrichment:

curl -X POST https://tasks.example.com/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team standup",
    "due_at": "2026-02-15T15:00:00Z",
    "priority": 2,
    "rrule": "FREQ=WEEKLY;BYDAY=MO,WE,FR",
    "labels": ["work"],
    "project_id": 1
  }'

AI enrichment only triggers for title-only tasks (no due_at, priority=0, no labels, no rrule).

Response Format

Success: { "data": { ... } }

Error: { "error": "message", "code": "ERROR_CODE" }

Status	Meaning
200	Success
201	Created
400	Validation error
401	Unauthorized
403	Forbidden
404	Not found
500	Internal error

OpenAPI Specification

A machine-readable API spec is available at GET /api/openapi (no auth required). OpenAPI 3.1 YAML covering all public endpoints. Use it to generate client libraries or browse the interactive API Reference.

iOS Shortcuts Tips

1. Use "Get Contents of URL" action with method POST
2. Add Authorization: Bearer $TOKEN and Content-Type: application/json headers
3. Set Request Body to JSON with a single title key containing the dictated text
4. Name the shortcut "Add Task" for "Hey Siri, Add Task"
5. Parse data.id from the response to confirm creation