0.x — pre-release, no compatibility promise yet.What this means

Overview

Taskadence API 2026-09-25

The Taskadence public API: JSON over HTTPS, under /v1.

Authentication: a Taskadence access token (TaskadenceToken - one organization, scopes you choose, optionally limited to some projects; admin implies every scope) or a Supabase session JWT.
Errors: always application/problem+json with type, title, status, detail, instance and request_id. The types are listed below.
Lists: {data, next_cursor}. Page with limit and cursor; order with sort_by and sort_order.
Conditional requests: single reads return an ETag. Send it as If-None-Match for a 304, or as If-Match on a write - a stale one is a 412.
Safe retries: creates honour an Idempotency-Key for 24 h.
Search: GET /v1/tasks?filter[search]=….

Problem types

`type`	Meaning
`about:blank`	A plain HTTP error; the status and `detail` say everything.
`urn:taskadence:problem:validation`	The request body or query did not validate. `errors` lists each failure (`loc`, `msg`, `type`).
`urn:taskadence:problem:invalid-parameter`	A query parameter is outside what the operation accepts; `errors[].allowed` lists the valid values.
`urn:taskadence:problem:precondition-failed`	`If-Match` did not match the resource’s current `ETag` - re-read it and retry.
`urn:taskadence:problem:idempotency-key-reused`	This `Idempotency-Key` was first used for a different request (method, path or body).
`urn:taskadence:problem:idempotency-key-in-flight`	The first request with this `Idempotency-Key` has not finished; retry shortly.
`urn:taskadence:problem:idempotency-key-invalid`	`Idempotency-Key` must be 1–255 printable ASCII characters.
`urn:taskadence:problem:rate-limit`	Too many requests with this access token, or a signed-in user, or an address; wait `Retry-After` seconds (`X-RateLimit-*` say where you stand).
`urn:taskadence:problem:internal`	An unexpected server error. Quote `request_id` to support.
`urn:taskadence:problem:token-invalid`	The access token is unknown or malformed (or its principal no longer exists).
`urn:taskadence:problem:token-expired`	The access token is past its `expires_at`; mint a new one.
`urn:taskadence:problem:token-revoked`	The access token was revoked (by its owner, an admin, a rotation, or its service account’s deactivation).
`urn:taskadence:problem:insufficient-scope`	The access token does not carry the scope this operation needs (`errors[0].required`; null = not available to tokens).
`urn:taskadence:problem:test-token-read-only`	A `tkd_test_` token can authenticate and read, never write.
`urn:taskadence:problem:token-policy`	The organization’s token policy refuses this token (personal tokens off, expiry required, or past the maximum lifetime).
`urn:taskadence:problem:url-refused`	The webhook URL is refused: not https, carries credentials, or resolves to a private, loopback, link-local, metadata, multicast or reserved address (`errors[0].reason`).
`urn:taskadence:problem:mfa-required`	The organization requires two-step sign-in and this session signed in with one step. `mfa.enrolled` says whether the person has an authenticator app set up (sign in with it) or must set one up first; `mfa.required_for` is `all` or `admins`. Access tokens are not affected.
`urn:taskadence:problem:email-unverified`	The signed-in person has not confirmed their email address yet. Confirm it from the email that was sent (or ask for a new one), then retry. Access tokens are not affected.
`urn:taskadence:problem:upload-too-large`	The file is over the size limit (`detail` names it): 25 MB for attachments and project files, 2 MB for an avatar. A zip whose contents unpack to over 10 times the limit counts as too large.
`urn:taskadence:problem:upload-type-not-allowed`	The file’s type is not allowed (`detail` lists the allowed types). Executables, scripts, HTML, SVG, XML and macro-enabled Office files are never accepted, nor a zip holding one.
`urn:taskadence:problem:upload-type-mismatch`	The file’s contents are not what its extension (or its declared content type) says, for example an executable named `.png`, or a `.txt` that is not UTF-8 text.
`urn:taskadence:problem:upload-rejected`	The malware scan refused the file (422), or could not scan it right now (503: retry later).

Information

OpenAPI version: 3.1.0

Authentication

bearerAuth

A Supabase session token (Authorization: Bearer <jwt>) - what the Taskadence app sends. It holds every scope. Rate limit: 600 requests a minute per user, apart from any token’s; every response carries X-RateLimit-*.

Security scheme type: http

Bearer format: JWT

TaskadenceToken

A Taskadence access token: Authorization: Bearer tkd_live_….

Minting: POST /v1/tokens (or Developers → Tokens in the app). The token is shown once.
Reach: one organization, optionally limited to some of its projects.
Scopes: each operation’s x-scopes names the one it needs. admin implies every scope; <ns>:write implies <ns>:read; org:read implies members:read.
Test tokens: tkd_test_… tokens authenticate and read, but never write.
Rate limit: 600 requests a minute per token (60 for a test token). Every response carries X-RateLimit-*; over the limit is a 429 with Retry-After.
Internal operations refuse every token (403 insufficient-scope with required: null).

Scope	Grants
`tasks:read`	Read tasks, their comments, attachments, history, sections and saved views.
`tasks:write`	Create, update and delete tasks, comments, attachments, sections and saved views (implies tasks:read).
`projects:read`	Read projects, their members, resources, statistics, goals and milestones.
`projects:write`	Create, update and delete projects, their members, resources, goals and milestones (implies projects:read).
`teams:read`	Read teams, their members, sprints and availability.
`teams:write`	Create, update and delete teams, their members, sprints and availability (implies teams:read).
`members:read`	Read the organization’s profile, its members (role, designation, active) and the designation catalog.
`org:read`	Read the organization, its settings, members, invites, designations, access tokens and access review (implies members:read).
`org:write`	Change the organization’s settings, members, invites and designations; mint, rotate and revoke access tokens and service accounts (implies org:read).
`webhooks:read`	Read the organization’s webhooks and their delivery logs (owner / admin, or a service account).
`webhooks:write`	Create, change, pause, test, rotate and delete webhooks and replay deliveries (implies webhooks:read).
`admin`	Every scope, including the audit log.

Security scheme type: http

Bearer format: tkd_live_… / tkd_test_…

oauth2

For third-party apps acting for a Taskadence user: the authorization-code flow with PKCE (S256, required). The access token it returns is a tkd_live_… token for one organization, valid 1 hour; refresh tokens rotate on every use.

Security scheme type: oauth2

Flow type: authorizationCode

Authorization URL: https://api.taskadence.com/oauth/authorize

Token URL: https://api.taskadence.com/oauth/token

Refresh URL: https://api.taskadence.com/oauth/token

Scopes:

tasks:read - Read tasks, their comments, attachments, history, sections and saved views.
tasks:write - Create, update and delete tasks, comments, attachments, sections and saved views (implies tasks:read).
projects:read - Read projects, their members, resources, statistics, goals and milestones.
projects:write - Create, update and delete projects, their members, resources, goals and milestones (implies projects:read).
teams:read - Read teams, their members, sprints and availability.
teams:write - Create, update and delete teams, their members, sprints and availability (implies teams:read).
members:read - Read the organization's profile, its members (role, designation, active) and the designation catalog.
org:read - Read the organization, its settings, members, invites, designations, access tokens and access review (implies members:read).
org:write - Change the organization's settings, members, invites and designations; mint, rotate and revoke access tokens and service accounts (implies org:read).
webhooks:read - Read the organization's webhooks and their delivery logs (owner / admin, or a service account).
webhooks:write - Create, change, pause, test, rotate and delete webhooks and replay deliveries (implies webhooks:read).
admin - Every scope, including the audit log.