{ "openapi": "3.1.0", "info": { "title": "GetItDone API", "version": "1.0.0", "description": "The public GetItDone REST API — AI-native task management for people and agents. Authenticate with a `gid_` API key (or OAuth 2.1 access token) via `Authorization: Bearer`.", "contact": { "name": "GetItDone support", "url": "https://nowgetitdone.com", "email": "support@devino.ca" } }, "servers": [ { "url": "https://app.nowgetitdone.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Organizations", "description": "Organizations (workspaces) — the tenant every task, project and API credential belongs to." }, { "name": "Usage", "description": "Plan usage — billing period, per-meter consumption, and the per-credential burst policy." }, { "name": "Members", "description": "The organization's member roster." }, { "name": "Projects", "description": "Named groupings of tasks within an organization." }, { "name": "API keys", "description": "The organization's API credentials — list, mint and revoke." }, { "name": "Tasks", "description": "Tasks — the core work items. Public ids are product short ids (`T-123`); every content change is an immutable version, browsable via the history endpoint." }, { "name": "Daily plan", "description": "The credential user's per-date daily board: a TODO (plan) section and a PROGRESS section, each holding planned tasks." }, { "name": "Attachments", "description": "Task file attachments — two-phase presigned uploads and short-lived presigned downloads." }, { "name": "Webhook endpoints", "description": "Outbound customer webhook endpoints (PRO+) — register, verify, rotate secrets, send test events, and read the delivery log." } ], "paths": { "/v1/organizations": { "get": { "operationId": "listOrganizations", "summary": "List organizations", "description": "Lists the organizations this credential can access. A credential is bound to exactly one organization today, so the list always fits one page.", "tags": [ "Organizations" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "workspaces:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "responses": { "200": { "description": "The organizations visible to this credential.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationList" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/organizations/{organization_id}": { "get": { "operationId": "getOrganization", "summary": "Get an organization", "description": "Fetches a single organization by id. The id MUST equal this credential's own organization — any other id (including one that genuinely exists for a different tenant) answers 404 `resource_not_found`; there is no cross-org existence oracle.", "tags": [ "Organizations" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "workspaces:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "description": "Must equal the credential's own organization id." }, "required": true, "description": "Must equal the credential's own organization id." } ], "responses": { "200": { "description": "The organization.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Get plan usage", "description": "Reports the current billing period, per-meter consumption against the plan, and the per-credential burst allowance. Reading usage never consumes the API-call quota (the meter cost is zero), so this endpoint stays reachable even when the period allowance is exhausted.", "tags": [ "Usage" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "usage:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 0 }, "responses": { "200": { "description": "The organization's current usage snapshot.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/members": { "get": { "operationId": "listMembers", "summary": "List members", "description": "Cursor-paginated list of the credential's organization members, newest membership first.", "tags": [ "Members" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "members:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." } ], "responses": { "200": { "description": "Page of the organization's members.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/projects": { "get": { "operationId": "listProjects", "summary": "List projects", "description": "Cursor-paginated list of the credential's organization projects, newest first.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "projects:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." } ], "responses": { "200": { "description": "Page of the organization's projects.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "Creates a project in the credential's organization. Supports the optional `Idempotency-Key` header for safe retries; a project name that already exists in this organization answers 400 `validation_failed` with a `/name` field error (the uniqueness rule the in-app project creator also enforces) — note that when an Idempotency-Key IS supplied, that 400 is itself stored and replayed byte-identically on retry with the SAME key, exactly like any other outcome (D5).", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "projects:write" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectBody" } } } }, "responses": { "201": { "description": "The created project.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/projects/{project_id}": { "get": { "operationId": "getProject", "summary": "Get a project", "description": "Fetches a single project by id, scoped to the credential's organization. A project id from another organization (or an unknown id) answers 404 `resource_not_found` — no cross-org existence oracle.", "tags": [ "Projects" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "projects:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "project_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The project.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "Cursor-paginated list of the organization's API keys (both generations), metadata only — never hashes or plaintext secrets.", "tags": [ "API keys" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "api-keys:manage" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." } ], "responses": { "200": { "description": "Page of the organization's API keys.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createApiKey", "summary": "Create an API key", "description": "Mints a new org-owned API key. Beyond the `api-keys:manage` scope check, the CALLING credential's creator must currently hold an owner/admin membership in the organization — a key minted while its creator was an admin stops being able to mint further keys the moment that user is demoted (403 `insufficient_scope`). Supports the optional `Idempotency-Key` header; note the replay caution: a replayed response includes the ORIGINAL plaintext `key` again within the 24h replay window (the same tradeoff Stripe makes for idempotent secret-bearing responses) — treat a stored Idempotency-Key as equally sensitive to the secret itself.", "tags": [ "API keys" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "api-keys:manage" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyBody" } } } }, "responses": { "201": { "description": "The created key, with its plaintext secret shown once.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/api-keys/{key_id}": { "delete": { "operationId": "deleteApiKey", "summary": "Revoke an API key", "description": "Revokes an API key (either generation) — org-scoped; an id from another organization or an unknown id answers 404 `resource_not_found` (no cross-org existence oracle). A key revoking ITSELF is allowed: the credential is only checked at the top of the request, before the revoke runs. DELETE is naturally idempotent by HTTP semantics — this route does not use the Idempotency-Key ledger.", "tags": [ "API keys" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "api-keys:manage" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "key_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The key was revoked.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokedApiKey" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tasks": { "get": { "operationId": "listTasks", "summary": "List tasks", "description": "Cursor-paginated list of the credential organization's tasks (current version of each), most recently updated first. Filters: `status`, `project_id`, `parent_task_id` (subtasks of one task) and `archived` (default false — archived tasks are excluded). Every filter is baked into the cursor: reusing an `after` cursor with different filters answers 400 `validation_failed`.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." }, { "in": "query", "name": "status", "schema": { "description": "Only tasks whose CURRENT version has this status.", "$ref": "#/components/schemas/TaskStatus" }, "description": "Only tasks whose CURRENT version has this status." }, { "in": "query", "name": "project_id", "schema": { "description": "Only tasks whose CURRENT version is linked to this project.", "type": "string" }, "description": "Only tasks whose CURRENT version is linked to this project." }, { "in": "query", "name": "parent_task_id", "schema": { "description": "Only direct subtasks of this task. An unknown (or other-organization) parent answers 404 `resource_not_found`.", "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "example": "T-123" }, "description": "Only direct subtasks of this task. An unknown (or other-organization) parent answers 404 `resource_not_found`." }, { "in": "query", "name": "archived", "schema": { "default": "false", "description": "true = ONLY archived tasks; false (default) = only active tasks.", "type": "string", "enum": [ "true", "false" ] }, "description": "true = ONLY archived tasks; false (default) = only active tasks." } ], "responses": { "200": { "description": "Page of tasks.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createTask", "summary": "Create a task", "description": "Creates a task in the credential's organization, owned by the credential's user — the SAME operation the external MCP `create_task` tool executes. `project_id` / `parent_task_id` additionally link the new task org-scoped (unknown ids answer 400 `validation_failed`). Supports the optional `Idempotency-Key` header for exactly-once retries.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskBody" } } } }, "responses": { "201": { "description": "The created task.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tasks/{task_id}": { "get": { "operationId": "getTask", "summary": "Get a task", "description": "Fetches a single task by short id, scoped to the credential's organization. A short id from another organization (or an unknown one) answers 404 `resource_not_found` — no cross-org existence oracle.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." } ], "responses": { "200": { "description": "The task.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateTask", "summary": "Update a task", "description": "Partial update — the SAME operation the external MCP `update_task` tool executes: it writes a NEW immutable version carrying every omitted field (and the project links, attachments and collaborators) over from the current one. The change appears as a new entry in the task history.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskBody" } } } }, "responses": { "200": { "description": "The updated task.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tasks/{task_id}/archive": { "post": { "operationId": "archiveTask", "summary": "Archive a task", "description": "Archives the task (hides it from active lists; no data is deleted) — the SAME operation the external MCP `archive_task` tool executes. Archiving an already-archived task succeeds unchanged. Supports the optional `Idempotency-Key` header.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "responses": { "200": { "description": "The archived task.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tasks/{task_id}/unarchive": { "post": { "operationId": "unarchiveTask", "summary": "Unarchive a task", "description": "Restores an archived task to the active lists — the archive operation with `archive: false`, exactly as the MCP `archive_task` tool exposes it. Supports the optional `Idempotency-Key` header.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "responses": { "200": { "description": "The unarchived task.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tasks/{task_id}/history": { "get": { "operationId": "listTaskHistory", "summary": "List task history", "description": "Cursor-paginated, read-only version history of a task, newest first — every content change (in-app, MCP or this API) is an immutable version snapshot. This is the ONE endpoint where versions surface; their ids are accepted nowhere else.", "tags": [ "Tasks" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." }, { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." } ], "responses": { "200": { "description": "Page of version snapshots.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskHistoryList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/daily-plan": { "get": { "operationId": "getDailyPlan", "summary": "Get the daily board", "description": "The credential user's board for a date: both sections (TODO plan + PROGRESS) with their fill-status and entries. Read-only — unlike the in-app board it never creates section rows; a date nobody planned answers empty sections with status NOT_FILLED.", "tags": [ "Daily plan" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "date", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Board date as YYYY-MM-DD (UTC day).", "example": "2026-07-23" }, "required": true, "description": "Board date as YYYY-MM-DD (UTC day)." } ], "responses": { "200": { "description": "The date's board.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPlan" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "setDailyPlanStatus", "summary": "Set a section's daily status", "description": "Sets the fill-status of one section of the credential user's board for a date (creating the section row if the date was never touched — the in-app board creates it on view).", "tags": [ "Daily plan" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "date", "schema": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Board date as YYYY-MM-DD (UTC day).", "example": "2026-07-23" }, "required": true, "description": "Board date as YYYY-MM-DD (UTC day)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDailyPlanStatusBody" } } } }, "responses": { "200": { "description": "The updated section status.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPlanStatus" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/daily-plan/entries": { "post": { "operationId": "createDailyPlanEntry", "summary": "Plan a task onto the board", "description": "Pins a task (current version) onto one section of the credential user's board for a date — mirroring the in-app add: only tasks OWNED by the credential's user and not archived can be planned; a parent task brings its subtasks along; a task already on that section answers 400 `validation_failed`. Supports the optional `Idempotency-Key` header.", "tags": [ "Daily plan" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDailyPlanEntryBody" } } } }, "responses": { "201": { "description": "The created board entry.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPlanEntry" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/daily-plan/entries/{entry_id}": { "patch": { "operationId": "moveDailyPlanEntry", "summary": "Move an entry between sections", "description": "Moves a board entry to the other section of the same date, mirroring the in-app move: subtask entries of a parent move along, a task already present in the target section answers 400 `validation_failed`, and the move RE-CREATES the entry — the returned entry carries a NEW id. Sections are the only movement the board models (no positional reorder exists).", "tags": [ "Daily plan" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "entry_id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveDailyPlanEntryBody" } } } }, "responses": { "200": { "description": "The entry in its new section (new id).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPlanEntry" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteDailyPlanEntry", "summary": "Remove an entry from the board", "description": "Removes a board entry (the task itself is untouched), mirroring the in-app remove: a parent entry takes its subtasks' entries on the same board with it. An entry from another organization or user answers 404 `resource_not_found`.", "tags": [ "Daily plan" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "entry_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Removal acknowledgement.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedDailyPlanEntry" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tasks/{task_id}/attachments": { "get": { "operationId": "listTaskAttachments", "summary": "List task attachments", "description": "Cursor-paginated attachments of the task's CURRENT version, newest first (metadata only — mint download URLs per attachment via the `download-url` endpoint).", "tags": [ "Attachments" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." }, { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." } ], "responses": { "200": { "description": "Page of attachments.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createTaskAttachment", "summary": "Register an uploaded attachment", "description": "Phase 2 of the two-phase upload: attaches the uploaded file (by its `file_key`) to the task's CURRENT version — exactly how the in-app flow registers uploads after the presigned PUT. Supports the optional `Idempotency-Key` header for exactly-once retries.", "tags": [ "Attachments" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttachmentBody" } } } }, "responses": { "201": { "description": "The registered attachment.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/tasks/{task_id}/attachments/uploads": { "post": { "operationId": "createAttachmentUpload", "summary": "Start an attachment upload", "description": "Phase 1 of the two-phase upload (the SAME presign flow the in-app uploader uses): declares the file and answers a short-lived presigned PUT URL plus the `file_key` to register afterwards. Checked against the plan's file-size and storage allowances. Nothing is attached until phase 2. Supports the optional `Idempotency-Key` header (a replay returns the SAME URL, which may have expired — start a fresh upload instead of replaying old keys).", "tags": [ "Attachments" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:write" ], "x-entitlement": "public_api", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "task_id", "schema": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "required": true, "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input)." }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAttachmentUploadBody" } } } }, "responses": { "201": { "description": "Where to PUT the file.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentUpload" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/attachments/{attachment_id}/download-url": { "get": { "operationId": "getAttachmentDownloadUrl", "summary": "Mint an attachment download URL", "description": "Answers a short-lived presigned GET URL for the attachment's bytes (the SAME signer the in-app proxy and the MCP `get_task_details` tool use). An attachment from another organization (or an unknown id) answers 404 `resource_not_found`.", "tags": [ "Attachments" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "tasks:read" ], "x-entitlement": "public_api", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "attachment_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The presigned download URL.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentDownloadUrl" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Cursor-paginated list of the organization's webhook endpoints. PRO plan and above (`outbound_webhooks`) — a FREE-plan credential gets 403 `feature_not_enabled`. Never includes signing secrets.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:read" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." } ], "responses": { "200": { "description": "Page of the organization's webhook endpoints.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Registers a new webhook endpoint in the credential's organization and mints its signing secret, returned EXACTLY ONCE in this response. The endpoint starts UNVERIFIED (`verified: false`) — call the `verify` action before relying on it; the worker only queues deliveries to enabled AND verified endpoints. The URL is validated at save time (https, port 443, no embedded credentials) — a disallowed URL answers 422 `webhook_url_rejected` and creates NO row. Supports the optional `Idempotency-Key` header; a replayed response includes the ORIGINAL plaintext secret again within the 24h replay window (same tradeoff as `createApiKey`).", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointBody" } } } }, "responses": { "201": { "description": "The created endpoint, with its plaintext secret shown once.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`. `webhook_url_rejected`: Webhook endpoint URL rejected.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{endpoint_id}": { "get": { "operationId": "getWebhookEndpoint", "summary": "Get a webhook endpoint", "description": "Fetches a single webhook endpoint by id, scoped to the credential's organization. An id from another organization (or an unknown id) answers 404 `resource_not_found` — no cross-org existence oracle. Never includes the signing secret.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:read" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The webhook endpoint.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Partial update of url/event_types/enabled — org-scoped, 404 for a cross-org or unknown id. NEVER rotates the secret (use the `rotate-secret` action). Changing `url` to a different value resets `verified` to false. The (re-validated) URL check can answer 422 `webhook_url_rejected`.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointBody" } } } }, "responses": { "200": { "description": "The updated endpoint.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`webhook_url_rejected`: Webhook endpoint URL rejected.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Permanently (hard) deletes the endpoint — org-scoped, 404 for a cross-org or unknown id — mirroring how `deleteApiKey` hard-deletes a plugin key. The delete CASCADES (schema.prisma `onDelete: Cascade` on WebhookDelivery.endpointId, and from there to WebhookAttempt) to every delivery still queued for this endpoint: pending/in-flight deliveries for this endpoint stop existing rather than being left stuck. DELETE is naturally idempotent by HTTP semantics — this route does not use the Idempotency-Key ledger.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The endpoint was deleted.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedWebhookEndpoint" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/rotate-secret": { "post": { "operationId": "rotateWebhookEndpointSecret", "summary": "Rotate a webhook endpoint secret", "description": "Create-overlap-revoke rotation: mints a NEW signing secret (returned ONCE, same as create) and moves the CURRENT secret to `previous_secret_expires_at`-bounded overlap — the worker signs every delivery with BOTH secrets during that ~24h window so you can finish updating your verifier without dropping deliveries. Rotating a SECOND time before the first rotation's grace window elapses immediately drops the FIRST previous secret (there is only ever one previous-secret slot, not a stack) — do not chain rotations faster than your own verifier can keep up. Never mutates a secret in place; always mints fresh. Supports the optional `Idempotency-Key` header (a replay returns the SAME newly-minted secret again, never rotates twice for one logical request).", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": true, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true }, { "in": "header", "name": "Idempotency-Key", "schema": { "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Optional client-generated key (1-255 visible ASCII characters; a UUID works) making this POST safely retryable. Retrying with the SAME key and byte-identical body within 24h replays the stored first response (marked `Idempotency-Replayed: true`, never re-executed, never charged against quota). The same key with a different body answers 422 `idempotency_key_reused`; a retry racing the first execution answers 409 `idempotency_in_progress`. Omitting the header executes normally with no idempotency guarantee." } ], "responses": { "200": { "description": "The endpoint with its newly rotated secret.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedWebhookEndpointSecret" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still executing — `idempotency_in_progress`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Idempotency-Key reused with a different request body — `idempotency_key_reused`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/verify": { "post": { "operationId": "verifyWebhookEndpoint", "summary": "Verify a webhook endpoint", "description": "Live, synchronous probe: SSRF-checks the stored URL, then POSTs a signed synthetic test request (Standard Webhooks headers; event type `webhook.verification` — NOT part of the delivery vocabulary, never persisted as a WebhookEvent) and requires a 2xx to mark the endpoint verified. This is a re-runnable probe, not a consequential write — no Idempotency-Key support (`idempotent: false`). A failure reports `verified: false` with a `reason` and does NOT unset a previously-earned verified state.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "The verification probe result.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointVerificationResult" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/test-event": { "post": { "operationId": "testWebhookEndpointEvent", "summary": "Send a test event to a webhook endpoint", "description": "Sends a synchronous, signed sample of a REAL event type (default `task.created`, using a representative sample task payload in the same TaskDto shape real deliveries carry) directly to the endpoint's URL and returns the immediate HTTP outcome. Does NOT create a queued WebhookDelivery row and never appears in the delivery log — it is a live probe, not a domain event. Re-runnable; no Idempotency-Key support.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointTestEventBody" } } } }, "responses": { "200": { "description": "The immediate delivery outcome.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointTestEventResult" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/deliveries": { "get": { "operationId": "listWebhookEndpointDeliveries", "summary": "List a webhook endpoint delivery log", "description": "Cursor-paginated, REDACTED delivery log for one endpoint — org-scoped via the endpoint (404 for a cross-org or unknown endpoint id). Never includes response bodies or the signing secret. Optional `state` filter.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:read" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of items to return (1-100).", "example": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum number of items to return (1-100)." }, { "in": "query", "name": "after", "schema": { "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`.", "type": "string" }, "description": "Opaque cursor from a previous page's `next_cursor` — omit for the first page. Reusing a cursor with DIFFERENT query parameters (e.g. a different `limit`) answers 400 `validation_failed`." }, { "in": "query", "name": "state", "schema": { "description": "Filter to deliveries currently in this state.", "example": "FAILED", "$ref": "#/components/schemas/WebhookDeliveryState" }, "description": "Filter to deliveries currently in this state." }, { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Page of the endpoint's delivery log.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/deliveries/{delivery_id}/replay": { "post": { "operationId": "replayWebhookDelivery", "summary": "Replay a webhook delivery", "description": "Re-enqueues one delivery, Stripe-style: creates a FRESH PENDING WebhookDelivery row for the SAME event and endpoint (attempt count 0, next attempt now) that the worker picks up on its normal cycle — the original row is never mutated, so the log keeps the full history. Allowed only when the target delivery is in a terminal state (FAILED, SUCCEEDED or DISABLED — replaying a succeeded delivery is a deliberate resend). Answers 409 `delivery_already_pending` when ANY delivery for this event+endpoint pair is already PENDING or DELIVERING (no double-enqueue) — which also makes an accidental double-click naturally safe, so this route does not use the Idempotency-Key ledger. The replayed delivery carries the SAME `webhook-id` signature header as the original (the event id), so consumer-side dedup keeps working. Replaying does NOT re-enable a disabled endpoint — the worker only delivers to enabled endpoints; re-enable via the update route first.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "delivery_id", "schema": { "type": "string" }, "required": true } ], "responses": { "202": { "description": "The freshly enqueued replay delivery.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`delivery_already_pending`: A delivery for this event is already queued.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/webhook-endpoints/{endpoint_id}/replay-failed": { "post": { "operationId": "replayFailedWebhookDeliveries", "summary": "Replay all recently failed deliveries", "description": "Bulk sibling of the single replay: creates FRESH PENDING deliveries for this endpoint's FAILED/DISABLED deliveries created at or after `since`, skipping every event that already has a PENDING/DELIVERING delivery queued for this endpoint (no double-enqueue) — hard-capped at 1000 replays per call (call again with the same `since` for the rest; already-replayed events are skipped by the pending check). Repeating the call is naturally near-idempotent for the same reason, so this route does not use the Idempotency-Key ledger. Does NOT re-enable a disabled endpoint — the “re-enable & replay” console flow is: update `enabled: true` (which resets the failure counter), then call this.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] } ], "x-scopes": [ "webhooks:write" ], "x-entitlement": "outbound_webhooks", "x-idempotent": false, "x-meter": { "metric": "API_CALLS", "cost": 1 }, "parameters": [ { "in": "path", "name": "endpoint_id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayFailedWebhookDeliveriesBody" } } } }, "responses": { "202": { "description": "How many deliveries were re-enqueued.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } }, "RateLimit-Policy": { "required": true, "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`.", "schema": { "type": "string", "description": "IETF draft-11 structured-field policy list, burst window first, e.g. `\"per-key-minute\";q=120;w=60, \"api-calls-period\";q=50000;w=2592000`." } }, "RateLimit": { "required": true, "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`.", "schema": { "type": "string", "description": "IETF draft-11 current state of the primary (burst) policy, e.g. `\"per-key-minute\";r=97;t=42`." } }, "X-RateLimit-Limit": { "required": true, "description": "Primary window request allowance (de-facto trio).", "schema": { "type": "string", "description": "Primary window request allowance (de-facto trio)." } }, "X-RateLimit-Remaining": { "required": true, "description": "Requests remaining in the primary window.", "schema": { "type": "string", "description": "Requests remaining in the primary window." } }, "X-RateLimit-Reset": { "required": true, "description": "Unix epoch seconds at which the primary window resets.", "schema": { "type": "string", "description": "Unix epoch seconds at which the primary window resets." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayedWebhookDeliveries" } } } }, "400": { "description": "Malformed request — `validation_failed` (see `errors`; a malformed `Idempotency-Key` header lands here too).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid credentials — `missing_credentials`, `invalid_api_key` or `invalid_token`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Authenticated but denied — `insufficient_scope` or `feature_not_enabled`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such resource in this organization — `resource_not_found`.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Over a limit — `rate_limited` (burst; retry after `Retry-After`) or `quota_exhausted` (billing-period allowance).", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Unexpected server error — `internal_error`; quote `request_id` when reporting.", "headers": { "x-request-id": { "required": true, "description": "Unique id for this request — present on EVERY response; quote it in support requests.", "schema": { "type": "string", "description": "Unique id for this request — present on EVERY response; quote it in support requests." } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "CreateProjectBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name, 1-200 characters after trimming.", "example": "Website redesign" }, "description": { "description": "Optional free-text description (max 2000 characters).", "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "name" ], "description": "Fields for creating a project." }, "CreateApiKeyBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Caller-given label for the key.", "example": "CI deploy bot" }, "scopes": { "description": "Subset of scopes to grant. Defaults to every scope EXCEPT `api-keys:manage` — key-minting is never granted by default and must be requested explicitly.", "type": "array", "items": { "type": "string", "enum": [ "workspaces:read", "tasks:read", "tasks:write", "members:read", "projects:read", "projects:write", "usage:read", "api-keys:manage", "webhooks:read", "webhooks:write" ] } }, "test_mode": { "description": "Mint a `gid_test_…` sandbox-prefixed key instead of a live one.", "type": "boolean" }, "expires_in_days": { "description": "Expiry in days from now (1-365). Omit for no expiry.", "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "name" ], "description": "Fields for minting a new API key." }, "TaskStatus": { "type": "string", "enum": [ "TODO", "IN_PROGRESS", "IN_REVIEW", "COMPLETED", "BLOCKED" ], "description": "Task workflow status." }, "CreateTaskBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Task title, 1-500 characters after trimming.", "example": "Ship the public API" }, "description": { "type": "string", "maxLength": 10000 }, "status": { "description": "Initial status (defaults to TODO).", "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "due_date": { "description": "Due date as YYYY-MM-DD (interpreted as UTC).", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "notes": { "type": "string", "maxLength": 100000 }, "story_points": { "type": "number", "minimum": 0, "maximum": 1000 }, "project_id": { "description": "Link the new task to this project (must belong to the credential's organization).", "type": "string" }, "parent_task_id": { "description": "Create as a subtask of this task (short id, must belong to the credential's organization).", "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "example": "T-123" } }, "required": [ "title" ], "description": "Fields for creating a task." }, "TaskPriority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "URGENT" ], "description": "Task priority level." }, "UpdateTaskBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "$ref": "#/components/schemas/TaskPriority" }, "due_date": { "description": "New due date as YYYY-MM-DD (interpreted as UTC). Cannot be cleared — the shared update operation treats absence as \"keep\".", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "notes": { "type": "string", "maxLength": 100000 }, "story_points": { "type": "number", "minimum": 0, "maximum": 1000 } }, "description": "Partial update — omitted fields keep their current value. Exactly the field set the external MCP `update_task` tool supports; `description`, project links and the parent are not updatable here (the shared update operation carries them over unchanged)." }, "SetDailyPlanStatusBody": { "type": "object", "properties": { "section": { "$ref": "#/components/schemas/DailySection" }, "status": { "$ref": "#/components/schemas/DailyStatus" } }, "required": [ "section", "status" ], "description": "Which section, and its new status." }, "DailySection": { "type": "string", "enum": [ "TODO", "PROGRESS" ], "description": "Daily-board section: `TODO` = the plan list, `PROGRESS` = the in-progress list." }, "DailyStatus": { "type": "string", "enum": [ "COMPLETED", "PLANNED", "NOT_FILLED", "FILLING" ], "description": "Fill-state of one daily-board section for one date." }, "CreateDailyPlanEntryBody": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Board date as YYYY-MM-DD (UTC day)." }, "task_id": { "type": "string", "pattern": "^(?:T-)?[0-9]{1,12}$", "description": "Task short id, e.g. `T-123` (a bare `123` is also accepted on input).", "example": "T-123" }, "section": { "$ref": "#/components/schemas/DailySection" } }, "required": [ "date", "task_id", "section" ], "description": "Which task, which date, which section." }, "MoveDailyPlanEntryBody": { "type": "object", "properties": { "section": { "$ref": "#/components/schemas/DailySection" } }, "required": [ "section" ], "description": "The target section." }, "CreateAttachmentBody": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255 }, "file_key": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The `file_key` returned by the upload endpoint." }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255 }, "size": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "File size in bytes as uploaded." } }, "required": [ "file_name", "file_key", "content_type", "size" ], "description": "Phase 2 of the two-phase upload: register the uploaded file on the task." }, "CreateAttachmentUploadBody": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "example": "screenshot.png" }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255, "example": "image/png" }, "size": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "File size in bytes — checked against the organization's plan file-size and storage allowances." } }, "required": [ "file_name", "content_type", "size" ], "description": "What you are about to upload." }, "CreateWebhookEndpointBody": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "The https destination URL. Must be https, port 443 (explicit or default), and carry no `user:pass@` credentials — a URL failing this check answers 422 `webhook_url_rejected` with the specific reason and creates NO row.", "example": "https://example.com/webhooks/getitdone" }, "event_types": { "description": "Subset of event types to subscribe to. Omit or send an empty array to subscribe to every type.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointEventType" } }, "enabled": { "description": "Defaults to true.", "type": "boolean" } }, "required": [ "url" ], "description": "Fields for registering a new webhook endpoint." }, "WebhookEndpointEventType": { "type": "string", "enum": [ "task.created", "task.updated", "task.archived" ], "description": "One of the frozen domain event types an endpoint can subscribe to." }, "UpdateWebhookEndpointBody": { "type": "object", "properties": { "url": { "description": "New destination URL, re-validated the same way as create. Changing the URL to a DIFFERENT value resets `verified` to false — the new destination must be re-verified.", "type": "string", "minLength": 1, "maxLength": 2048 }, "event_types": { "description": "Replaces the full subscribed-type set.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointEventType" } }, "enabled": { "description": "Enable or disable delivery. Re-enabling (false → true) clears any prior auto-disable reason and resets the consecutive-failure counter.", "type": "boolean" } }, "description": "Partial update — only send the fields you want to change; at least one is required." }, "CreateWebhookEndpointTestEventBody": { "type": "object", "properties": { "event_type": { "description": "Which sample event to send. Defaults to `task.created`.", "$ref": "#/components/schemas/WebhookEndpointEventType" } }, "description": "Optional choice of which sample event type to send." }, "WebhookDeliveryState": { "type": "string", "enum": [ "PENDING", "DELIVERING", "SUCCEEDED", "FAILED", "DISABLED" ], "description": "Lifecycle state of one (event, endpoint) delivery." }, "ReplayFailedWebhookDeliveriesBody": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Only FAILED/DISABLED deliveries created at or after this ISO-8601 instant are replayed.", "example": "2026-07-24T00:00:00Z" } }, "required": [ "since" ], "description": "Time window for the bulk replay." }, "OrganizationList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of organizations." }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable opaque organization id.", "example": "9f6acab2-8f8e-4c7e-9c3a-2f6d0c9e4b11" }, "name": { "type": "string", "description": "Display name.", "example": "Acme Inc" }, "slug": { "type": "string", "description": "URL-safe unique slug.", "example": "acme-inc" }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Logo URL, or null when none is set." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Creation time, ISO-8601 UTC.", "example": "2026-01-15T09:30:00.000Z" } }, "required": [ "id", "name", "slug", "image_url", "created_at" ], "additionalProperties": false, "description": "An organization (workspace) — the tenant every task, project and API credential belongs to." }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "URI identifying the problem class; resolves to its docs page.", "example": "https://nowgetitdone.com/docs/api/problems/validation-failed" }, "title": { "type": "string", "description": "Short human-readable summary of the problem class. Never parse it — switch on `code`." }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "HTTP status code, duplicated from the response.", "example": 400 }, "detail": { "description": "Human-readable explanation specific to this occurrence.", "type": "string" }, "code": { "type": "string", "enum": [ "missing_credentials", "invalid_api_key", "invalid_token", "insufficient_scope", "feature_not_enabled", "validation_failed", "resource_not_found", "rate_limited", "quota_exhausted", "idempotency_key_missing", "idempotency_key_reused", "idempotency_in_progress", "webhook_url_rejected", "delivery_already_pending", "internal_error" ], "description": "Stable machine-readable problem code — the value SDKs branch on." }, "request_id": { "type": "string", "description": "The x-request-id of the failing request — quote it in support requests." }, "errors": { "description": "Field-level failures (present on validation_failed).", "type": "array", "items": { "$ref": "#/components/schemas/FieldError" } } }, "required": [ "type", "title", "status", "code", "request_id" ], "additionalProperties": false, "description": "RFC 9457 problem document with the GetItDone `code` extension." }, "FieldError": { "type": "object", "properties": { "pointer": { "type": "string", "description": "RFC 6901 JSON Pointer to the offending request field.", "example": "/name" }, "code": { "type": "string", "description": "Machine-readable per-field validation code.", "example": "invalid_type" }, "message": { "type": "string", "description": "Human-readable explanation for this field." } }, "required": [ "pointer", "code", "message" ], "additionalProperties": false, "description": "A single field-level validation failure." }, "Usage": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "FREE", "PRO", "TEAM" ], "description": "The organization's current plan tier.", "example": "FREE" }, "period_start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Start of the current billing period, ISO-8601 UTC. Paid plans anchor at their subscription renewal; free plans at the first of the calendar month.", "example": "2026-07-01T00:00:00.000Z" }, "period_end": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "End of the current billing period, ISO-8601 UTC — when period meters reset.", "example": "2026-08-01T00:00:00.000Z" }, "meters": { "type": "array", "items": { "$ref": "#/components/schemas/UsageMeter" }, "description": "Per-meter consumption for the current period." }, "burst": { "type": "object", "properties": { "per_minute_limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Requests each individual credential may make per minute before 429 rate_limited.", "example": 10 } }, "required": [ "per_minute_limit" ], "additionalProperties": false, "description": "The per-credential burst policy (separate from period quotas; every key/token gets its own window)." } }, "required": [ "plan", "period_start", "period_end", "meters", "burst" ], "additionalProperties": false, "description": "The organization's consumption against its plan for the current billing period, plus the burst policy." }, "UsageMeter": { "type": "object", "properties": { "meter": { "type": "string", "enum": [ "api_calls" ], "description": "Which allowance this entry reports.", "example": "api_calls" }, "used": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Units consumed so far in the current period.", "example": 27 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The plan's allowance for this meter per period.", "example": 50 }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Units left before requests answer 429 quota_exhausted.", "example": 23 } }, "required": [ "meter", "used", "limit", "remaining" ], "additionalProperties": false, "description": "Consumption against one plan allowance." }, "MemberList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of an organization's members." }, "Member": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the membership row itself." }, "user": { "$ref": "#/components/schemas/MemberUser" }, "role": { "type": "string", "description": "The member's role in the organization.", "example": "owner" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When this membership was created, ISO-8601 UTC." } }, "required": [ "id", "user", "role", "created_at" ], "additionalProperties": false, "description": "One membership row — a user attached to this organization." }, "MemberUser": { "type": "object", "properties": { "id": { "type": "string", "description": "The member user id." }, "email": { "type": "string", "description": "The member's email address." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name, or null when never set." } }, "required": [ "id", "email", "name" ], "additionalProperties": false, "description": "The user identity behind a membership row." }, "ProjectList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of an organization's projects." }, "Project": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable opaque project id." }, "name": { "type": "string", "description": "Display name, unique within the organization.", "example": "Website redesign" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text description, or null when unset." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Creation time, ISO-8601 UTC." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Last-modified time, ISO-8601 UTC." } }, "required": [ "id", "name", "description", "created_at", "updated_at" ], "additionalProperties": false, "description": "A project — a named grouping of tasks within an organization." }, "ApiKeyList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of the organization's API keys." }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the key row." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller-given label." }, "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Non-secret fingerprint prefix shown in key lists (e.g. `gid_ab12`); never the full secret." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspaces:read", "tasks:read", "tasks:write", "members:read", "projects:read", "projects:write", "usage:read", "api-keys:manage", "webhooks:read", "webhooks:write" ] }, "description": "Scopes granted to this key." }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Last time this key authenticated a request, or null." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Expiry time, or null when the key never expires." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." }, "legacy": { "type": "boolean", "description": "True for a pre-migration user-owned key; false for a current org-owned key. Legacy keys are read-only here — mint new keys as non-legacy." } }, "required": [ "id", "name", "key_prefix", "scopes", "last_used_at", "expires_at", "created_at", "legacy" ], "additionalProperties": false, "description": "API-key metadata — never the hash or the plaintext secret." }, "CreatedApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the key row." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Caller-given label." }, "key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Non-secret fingerprint prefix shown in key lists (e.g. `gid_ab12`); never the full secret." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "workspaces:read", "tasks:read", "tasks:write", "members:read", "projects:read", "projects:write", "usage:read", "api-keys:manage", "webhooks:read", "webhooks:write" ] }, "description": "Scopes granted to this key." }, "last_used_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Last time this key authenticated a request, or null." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Expiry time, or null when the key never expires." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." }, "legacy": { "type": "boolean", "description": "True for a pre-migration user-owned key; false for a current org-owned key. Legacy keys are read-only here — mint new keys as non-legacy." }, "key": { "type": "string", "description": "The plaintext secret — shown EXACTLY ONCE. Store it now; it cannot be retrieved again.", "example": "gid_51f3...redacted" } }, "required": [ "id", "name", "key_prefix", "scopes", "last_used_at", "expires_at", "created_at", "legacy", "key" ], "additionalProperties": false, "description": "A freshly minted API key, including its one-time plaintext secret." }, "RevokedApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the revoked key." }, "legacy": { "type": "boolean", "description": "True when the revoked key was a legacy row (soft-revoked); false for a plugin key (deleted)." } }, "required": [ "id", "legacy" ], "additionalProperties": false, "description": "Confirmation that a key was revoked and can no longer authenticate." }, "TaskList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of tasks, most recently updated first." }, "Task": { "type": "object", "properties": { "id": { "type": "string", "description": "The task short id — the ONE public task identifier.", "example": "T-123" }, "title": { "type": "string", "example": "Ship the public API" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text description, or null when unset." }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "anyOf": [ { "$ref": "#/components/schemas/TaskPriority" }, { "type": "null" } ] }, "due_date": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Due date, ISO-8601 UTC, or null." }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Rich-text notes of the current version, or null." }, "story_points": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "project_ids": { "type": "array", "items": { "type": "string" }, "description": "Ids of the projects the CURRENT version is linked to (a task can belong to several)." }, "parent_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The parent task's short id when this is a subtask, else null.", "example": "T-99" }, "archived": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Task creation time (first version), ISO-8601 UTC." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Last content change (current version), ISO-8601 UTC." } }, "required": [ "id", "title", "description", "status", "priority", "due_date", "notes", "story_points", "project_ids", "parent_task_id", "archived", "created_at", "updated_at" ], "additionalProperties": false, "description": "A task, projected from its stable identity plus its CURRENT version." }, "TaskHistoryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskHistoryEntry" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of task versions, newest first." }, "TaskHistoryEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque version identifier — read-only; accepted nowhere else on this API." }, "title": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/TaskStatus" }, "priority": { "anyOf": [ { "$ref": "#/components/schemas/TaskPriority" }, { "type": "null" } ] }, "due_date": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "story_points": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When this version was written, ISO-8601 UTC." } }, "required": [ "id", "title", "description", "status", "priority", "due_date", "notes", "story_points", "created_at" ], "additionalProperties": false, "description": "One immutable content snapshot from a task's version history — the ONE place versions surface on this API." }, "DailyPlan": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "The board date (UTC day)." }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/DailyPlanSection" }, "description": "Always both sections: TODO then PROGRESS." } }, "required": [ "date", "sections" ], "additionalProperties": false, "description": "The credential user's daily board for one date in the credential's organization." }, "DailyPlanSection": { "type": "object", "properties": { "section": { "$ref": "#/components/schemas/DailySection" }, "status": { "$ref": "#/components/schemas/DailyStatus" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/DailyPlanEntry" }, "description": "Entries in placement order (oldest first)." } }, "required": [ "section", "status", "entries" ], "additionalProperties": false, "description": "One section of the user's board for one date." }, "DailyPlanEntry": { "type": "object", "properties": { "id": { "type": "string", "description": "Board-entry id. NOTE: moving an entry between sections re-creates it (mirroring the in-app move), so the id CHANGES on move." }, "section": { "$ref": "#/components/schemas/DailySection" }, "task_id": { "type": "string", "description": "The planned task's short id.", "example": "T-123" }, "title": { "type": "string", "description": "The planned task's current title." }, "status": { "description": "The planned task's current workflow status.", "$ref": "#/components/schemas/TaskStatus" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When the task was placed on this section, ISO-8601 UTC. Entries within a section are ordered by this (oldest first) — there is no free positional reorder." } }, "required": [ "id", "section", "task_id", "title", "status", "created_at" ], "additionalProperties": false, "description": "One task pinned onto one daily-board section." }, "DailyPlanStatus": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "section": { "$ref": "#/components/schemas/DailySection" }, "status": { "$ref": "#/components/schemas/DailyStatus" } }, "required": [ "date", "section", "status" ], "additionalProperties": false, "description": "One section's fill-status for one date." }, "DeletedDailyPlanEntry": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false, "description": "Acknowledgement of a removed board entry." }, "AttachmentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of the task's current-version attachments." }, "Attachment": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable opaque attachment id." }, "file_name": { "type": "string", "example": "screenshot.png" }, "content_type": { "type": "string", "example": "image/png" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "File size in bytes." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "file_name", "content_type", "size", "created_at" ], "additionalProperties": false, "description": "A file attached to a task's current version. Fetch its bytes via the `download-url` endpoint." }, "AttachmentUpload": { "type": "object", "properties": { "upload_url": { "type": "string", "description": "Presigned URL — PUT the raw file bytes here (Content-Type must match what you declared)." }, "upload_method": { "type": "string", "const": "PUT" }, "file_key": { "type": "string", "description": "Opaque storage key; pass it back when registering the attachment after the upload succeeds." }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When the upload URL stops working, ISO-8601 UTC." } }, "required": [ "upload_url", "upload_method", "file_key", "expires_at" ], "additionalProperties": false, "description": "Phase 1 of the two-phase upload: where to PUT the file." }, "AttachmentDownloadUrl": { "type": "object", "properties": { "url": { "type": "string", "description": "Presigned GET URL." }, "expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "When the URL stops working, ISO-8601 UTC." } }, "required": [ "url", "expires_at" ], "additionalProperties": false, "description": "A short-lived presigned download URL." }, "WebhookEndpointList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of the organization's webhook endpoints." }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the endpoint." }, "url": { "type": "string", "description": "The https destination URL." }, "enabled": { "type": "boolean", "description": "False when disabled — manually, or auto-disabled after repeated delivery failures (see `disabled_reason`)." }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointEventType" }, "description": "Subscribed event types. An EMPTY array means \"every type\"." }, "verified": { "type": "boolean", "description": "True once the `verify` action has proven this endpoint accepts a correctly-signed request." }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the endpoint was auto-disabled, or null when never auto-disabled." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." } }, "required": [ "id", "url", "enabled", "event_types", "verified", "disabled_reason", "created_at", "updated_at" ], "additionalProperties": false, "description": "A webhook endpoint configuration — NEVER includes the signing secret (shown once, at creation/rotation)." }, "CreatedWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the endpoint." }, "url": { "type": "string", "description": "The https destination URL." }, "enabled": { "type": "boolean", "description": "False when disabled — manually, or auto-disabled after repeated delivery failures (see `disabled_reason`)." }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointEventType" }, "description": "Subscribed event types. An EMPTY array means \"every type\"." }, "verified": { "type": "boolean", "description": "True once the `verify` action has proven this endpoint accepts a correctly-signed request." }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the endpoint was auto-disabled, or null when never auto-disabled." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." }, "secret": { "type": "string", "description": "The signing secret (`whsec_…`) — shown EXACTLY ONCE. Store it now; it cannot be retrieved again, only rotated. Note: replaying this exact request within the 24h Idempotency-Key window returns this SAME secret again — treat a stored Idempotency-Key as equally sensitive to the secret itself.", "example": "whsec_51f3...redacted" } }, "required": [ "id", "url", "enabled", "event_types", "verified", "disabled_reason", "created_at", "updated_at", "secret" ], "additionalProperties": false, "description": "A freshly registered endpoint, including its one-time signing secret. Starts UNVERIFIED — call the `verify` action to prove ownership before relying on deliveries." }, "DeletedWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the deleted endpoint." } }, "required": [ "id" ], "additionalProperties": false, "description": "Confirmation that the endpoint — and every pending/queued delivery for it — was permanently deleted." }, "RotatedWebhookEndpointSecret": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the endpoint." }, "url": { "type": "string", "description": "The https destination URL." }, "enabled": { "type": "boolean", "description": "False when disabled — manually, or auto-disabled after repeated delivery failures (see `disabled_reason`)." }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointEventType" }, "description": "Subscribed event types. An EMPTY array means \"every type\"." }, "verified": { "type": "boolean", "description": "True once the `verify` action has proven this endpoint accepts a correctly-signed request." }, "disabled_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the endpoint was auto-disabled, or null when never auto-disabled." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." }, "updated_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." }, "secret": { "type": "string", "description": "The NEW signing secret — shown EXACTLY ONCE.", "example": "whsec_51f3...redacted" }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "The prior secret keeps signing outgoing deliveries alongside the new one until this time (~24h out) — dual-secret acceptance so you can finish updating your verifier before the old secret dies." } }, "required": [ "id", "url", "enabled", "event_types", "verified", "disabled_reason", "created_at", "updated_at", "secret", "previous_secret_expires_at" ], "additionalProperties": false, "description": "Result of a create-overlap-revoke secret rotation. Rotating a SECOND time before the first rotation's grace window elapses immediately drops the FIRST previous secret — there is only ever one previous-secret slot, not a stack." }, "WebhookEndpointVerificationResult": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "True when the endpoint answered the signed test request with a 2xx status. On true, the endpoint's verified state is set." }, "status": { "description": "The HTTP status the endpoint returned, when a response was received at all (absent for a blocked/timed-out/network-failed probe).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reason": { "description": "Present when `verified` is false — why the probe failed.", "type": "string" } }, "required": [ "verified" ], "additionalProperties": false, "description": "Result of a live, synchronous verification probe. A failure does NOT unset a previously-earned verified state — only a success ever (re)sets it." }, "WebhookEndpointTestEventResult": { "type": "object", "properties": { "outcome": { "$ref": "#/components/schemas/WebhookTestEventOutcome" }, "status": { "description": "The HTTP status returned, when a response was received.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Wall-clock time the probe took." } }, "required": [ "outcome", "duration_ms" ], "additionalProperties": false, "description": "Result of a synchronous, signed sample-event delivery. This is a LIVE probe — it does not create a queued WebhookDelivery row, so it never appears in the delivery log." }, "WebhookTestEventOutcome": { "type": "string", "enum": [ "delivered", "blocked", "redirect_blocked", "request_failed", "timeout" ], "description": "The immediate outcome of the synchronous test POST." }, "WebhookDeliveryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" }, "description": "The current page of results." }, "has_more": { "type": "boolean", "description": "True when another page exists after this one." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page (pass as `after`); null on the last page." } }, "required": [ "data", "has_more", "next_cursor" ], "additionalProperties": false, "description": "Cursor-envelope page of one endpoint's delivery log." }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable id of the delivery row." }, "event_id": { "type": "string", "description": "The owning WebhookEvent's id — also the `webhook-id` signature header on the wire." }, "event_type": { "type": "string", "description": "The domain event type." }, "state": { "$ref": "#/components/schemas/WebhookDeliveryState" }, "attempt_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of delivery attempts made so far." }, "last_status": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "HTTP status of the most recent attempt, or null before any attempt has run." }, "next_attempt_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "When the next retry is scheduled, or null when not PENDING." }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO-8601 UTC." } }, "required": [ "id", "event_id", "event_type", "state", "attempt_count", "last_status", "next_attempt_at", "created_at" ], "additionalProperties": false, "description": "One delivery-log row — REDACTED: never includes response bodies or the signing secret." }, "ReplayedWebhookDeliveries": { "type": "object", "properties": { "replayed_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many FRESH PENDING deliveries this call created (capped at 1000 per call)." } }, "required": [ "replayed_count" ], "additionalProperties": false, "description": "Result of a bulk replay of failed deliveries." } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A `gid_` API key (Settings → API keys) or an OAuth 2.1 access token." } } } }