Restivity API

Quick Start

Canonical long-form reference: docs/api/README.md in the Restivity repository. The Redoc viewer below is the auto-generated machine reference.

1. Authentication — OAuth 2.0 + PKCE

Every /api/v1/* endpoint requires a Bearer token from the standard authorization_code grant with PKCE (RFC 7636). There is no API-key flow. Discover the OAuth server at /.well-known/oauth-authorization-server; register a client at POST /api/oauth/register; exchange the code at POST /api/oauth/token. Access tokens are signed JWTs (alg: ES256) verifiable with /api/oauth/jwks and expire in 1 hour. Refresh tokens rotate on each refresh; replaying a used refresh token revokes ALL of the client's tokens (RFC 6749 §10.4).

2. Scope model

Scopes are least-privilege. Each resource exposes :read and :write variants — tasks:read, tasks:write, projects:read, projects:write, pomodoro:read, pomodoro:write, profile:read, profile:write. The effective scope on a token is the intersection of (a) what the user consented to and (b) what the registered client requested. Calls outside the granted scope return 403 with WWW-Authenticate: Bearer error="insufficient_scope".

3. Pagination convention

List endpoints paginate via opaque cursor. Request: ?limit=<1-100, default 50>&cursor=<opaque>. Response wraps rows in { data: […], next_cursor: string | null }. next_cursor is nullwhen the current page is the last one — the nullability IS the "has-more" signal, no separate boolean. Filter via documented query parameters; multiple filters AND together.

4. Error shape

Every error response is RFC 9457 problem-details (Content-Type: application/problem+json). The body has { type, title, status, detail, instance } — plus scope_required on 403 and retry_after on 429. type is the issuer origin + /errors/<slug>: 400 invalid_request, 401 invalid_token, 403 insufficient_scope, 404 not_found (also for soft-deleted), 422 unprocessable, 429 rate_limited (with Retry-After), 500 internal, 503 service_unavailable.

Same handlers serve REST, MCP (/api/mcp), and the in-browser WebMCP read-only tools — see /.well-known/mcp/server-card.json for the MCP transport details.