REST API

Discover the deployed contract

On the application instance, /openapi.json exposes the full REST contract and /docs provides Swagger UI. This static project site does not host your private task API. The generated source reference lists current routes.

Access tokens

POST /api/auth/token accepts form-encoded username/email and password. Use the resulting token in Authorization: Bearer <token>. Tokens last up to 24 hours, bind to a stable user ID and current password state, and require the expected issuer, audience, token kind, timestamps, and HS256 signature. Current database roles, not a token's admin claim, control authorization.

curl --fail-with-body -X POST https://tasks.example.com/api/auth/token   --data-urlencode 'username=YOUR_USERNAME'   --data-urlencode 'password=YOUR_PASSWORD'
curl --fail-with-body https://tasks.example.com/api/auth/me   -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Avoid putting real passwords in shared terminals, shell history, tickets, or chat. Use your deployment's secure secret-entry mechanism. Upgrades from before 00.13.00 require replacing old tokens/sessions; the additive 00.14.01 upgrade does not require that migration again. Password changes and resets invalidate previously issued credentials.

Tasks and permissions

GET /api/tasks/ accepts limit (default 100, maximum 200), offset, search, status, tag, task type, sorting, and authorized administrator user filters. Adapt clients that previously assumed a listing returned every task. The summary endpoint returns archived, past-due, all-upcoming, and due-in-0–8h/8–24h/over-24h counts for the authenticated owner.

Task creation, update, archive, restore, and completion enforce ownership/administrator rules. Closing a parent with open subtasks returns 409 instead of an unhandled server error; close subtasks or use the website's explicit cascade confirmation. Completion uses a database claim to prevent two requests spawning the same next occurrence. Explicit JSON null clears a description or URL on update; omitted fields are unchanged.

Other API groups

/api/users/me reads/updates the authenticated profile; administrator user management is separate. Tags are listed for the authorized owner. Notification services and event status use /api/notifications; secret configuration values are redacted and masked round-trips preserve them. Database administration and global settings require an administrator. Treat JSON exports as secrets-bearing data.

ChatGPT-specific access

Private GPT Actions retain the owner-only /api/chatgpt routes and /openapi-chatgpt.json contract. Their revocable integration tokens are separate from both the original administrator API and MCP OAuth credentials. The REST password-grant endpoint is not an OAuth authorization-code flow.

Native MCP

When enabled, /mcp serves the MCP Streamable HTTP protocol and eleven tools. It is not a REST route to import as an Action schema. Discovery is available at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server. The associated OAuth endpoints are /authorize, /register, /token, and /revoke, with browser consent at /mcp/consent.

MCP clients use individual Timeboard sign-in, S256 PKCE, exact resource binding, and per-tool scopes. Version 00.14.01 also advertises authorization_response_iss_parameter_supported: true and includes the canonical iss identifier in successful and error authorization callbacks (RFC 9207). Existing JWTs and tba_... integration tokens do not authenticate to MCP. See ChatGPT setup and the scope table for activation, tools, ownership, assignment, and revocation. Native MCP is experimental and disabled by default.