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

Overview

TasksMate API 2026-09-25

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

Authentication: a TasksMate access token (TasksMateToken — 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:tasksmate:problem:validation`	The request body or query did not validate. `errors` lists each failure (`loc`, `msg`, `type`).
`urn:tasksmate:problem:invalid-parameter`	A query parameter is outside what the operation accepts; `errors[].allowed` lists the valid values.
`urn:tasksmate:problem:precondition-failed`	`If-Match` did not match the resource’s current `ETag` — re-read it and retry.
`urn:tasksmate:problem:idempotency-key-reused`	This `Idempotency-Key` was first used for a different request (method, path or body).
`urn:tasksmate:problem:idempotency-key-in-flight`	The first request with this `Idempotency-Key` has not finished; retry shortly.
`urn:tasksmate:problem:idempotency-key-invalid`	`Idempotency-Key` must be 1–255 printable ASCII characters.
`urn:tasksmate:problem:rate-limit`	Too many requests with this access token; wait `Retry-After` seconds (`X-RateLimit-*` say where you stand).
`urn:tasksmate:problem:internal`	An unexpected server error. Quote `request_id` to support.
`urn:tasksmate:problem:token-invalid`	The access token is unknown or malformed (or its principal no longer exists).
`urn:tasksmate:problem:token-expired`	The access token is past its `expires_at`; mint a new one.
`urn:tasksmate:problem:token-revoked`	The access token was revoked (by its owner, an admin, a rotation, or its service account’s deactivation).
`urn:tasksmate:problem:insufficient-scope`	The access token does not carry the scope this operation needs (`errors[0].required`; null = not available to tokens).
`urn:tasksmate:problem:test-token-read-only`	A `tm_test_` token can authenticate and read, never write.
`urn:tasksmate:problem:token-policy`	The organization’s token policy refuses this token (personal tokens off, expiry required, or past the maximum lifetime).
`urn:tasksmate: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`).

Information

OpenAPI version: 3.1.0

Authentication

bearerAuth

A Supabase session token (Authorization: Bearer <jwt>) — what the TasksMate app sends. It holds every scope.

Security scheme type: http

Bearer format: JWT

TasksMateToken

A TasksMate access token: Authorization: Bearer tm_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.
Test tokens: tm_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 roadmaps.
`projects:write`	Create, update and delete projects, their members, resources and goals (implies projects:read).
`teams:read`	Read teams, their members, sprints, milestones and availability.
`teams:write`	Create, update and delete teams, their members, sprints, milestones and availability (implies teams:read).
`org:read`	Read the organization, its settings, members, invites, designations, access tokens and access review.
`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: tm_live_… / tm_test_…

oauth2

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

Security scheme type: oauth2

Flow type: authorizationCode

Authorization URL: https://tasksmate-fdfsarhnf5gacfb7.eastus-01.azurewebsites.net/oauth/authorize

Token URL: https://tasksmate-fdfsarhnf5gacfb7.eastus-01.azurewebsites.net/oauth/token

Refresh URL: https://tasksmate-fdfsarhnf5gacfb7.eastus-01.azurewebsites.net/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 roadmaps.
projects:write - Create, update and delete projects, their members, resources and goals (implies projects:read).
teams:read - Read teams, their members, sprints, milestones and availability.
teams:write - Create, update and delete teams, their members, sprints, milestones and availability (implies teams:read).
org:read - Read the organization, its settings, members, invites, designations, access tokens and access review.
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.