{ "openapi": "3.1.0", "info": { "title": "Flowral API", "version": "1.0.0", "summary": "Client projects as dependency graphs — over HTTP.", "description": "The Flowral public API: flows, the tasks in them, and the derived state that\nmakes a dependency planner useful — what is ready, what is blocked, and when a\nproject actually lands.\n\n**Authentication.** Every request carries a credential created in the app under\n**API & AI**. Either send an API key as a bearer token, or exchange a client id\nand secret for a short-lived token at `POST /v1/oauth/token`. A credential\nbelongs to a workspace and carries its own role: it can never do more than that\nrole allows, and it cannot move between workspaces.\n\n**Errors** are `{ \"error\": { \"code\", \"message\" } }`. Switch on `code`; the\nmessage is for humans and may change.\n\n**Lists** are `{ \"total\", \"items\" }` and take `size` and `from`.\n\n**Rate limit** 120 requests/minute per credential, burst 240. Exceeding it\nreturns `429` with `Retry-After`.\n\n**Stability.** This is v1. Fields get added; nothing that exists is removed or\nrepurposed without a new major version. The platform API the web app uses is a\ndifferent, unversioned surface — it is not this, and it will change without\nnotice.", "contact": { "name": "Flowral", "email": "hello@flowral.app", "url": "https://flowral.app/api" }, "license": { "name": "Proprietary", "url": "https://flowral.app/terms" } }, "servers": [ { "url": "https://api.flowral.app", "description": "Production" } ], "tags": [ { "name": "auth", "description": "Getting a token." }, { "name": "workspace", "description": "Who the credential is." }, { "name": "flows", "description": "Projects, and everything that operates on a whole one." }, { "name": "tasks", "description": "The work, its dependencies, and moving it along." }, { "name": "work", "description": "Ready, blocked and in-progress work across every flow." }, { "name": "team", "description": "Members and invitations." }, { "name": "templates", "description": "Saved flow shapes." }, { "name": "search", "description": "Finding things by name." } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key from the app: `Authorization: Bearer fl_sk_live_…`." }, "oauth2": { "type": "oauth2", "description": "Client credentials, for anything long-lived.", "flows": { "clientCredentials": { "tokenUrl": "https://api.flowral.app/v1/oauth/token", "scopes": { "flows:read": "Read flows, tasks, schedules and reports", "flows:write": "Create and change flows and tasks", "work:write": "Start, complete, assign and comment on work", "team:read": "Read members and invitations", "team:write": "Invite people and change roles", "templates:read": "Read templates and start flows from them", "notifications:read": "Read what people are emailed about", "notifications:write": "Change what people are emailed about" } } } } }, "schemas": { "Error": { "type": "object", "description": "Every non-2xx response has this shape.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, machine-readable. Switch on this, not on the message.", "examples": [ "NOT_FOUND" ] }, "message": { "type": "string", "description": "Human-readable. May change; never parse it." }, "details": { "type": "object", "additionalProperties": true, "description": "Present when the code alone is not actionable — which task blocked, which deliverable is missing, which limit was hit." } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Context": { "type": "object", "description": "Who the credential is and what it may do — the first call to make when wiring an integration.", "properties": { "workspaceId": { "type": "string" }, "workspaceName": { "type": "string" }, "credentialId": { "type": "string", "description": "The key or client this token belongs to." }, "credentialName": { "type": "string", "examples": [ "Acme CI" ] }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "The credential’s role in the workspace. It decides what every other call may do." }, "scopes": { "type": "array", "items": { "type": "string" } }, "plan": { "type": "string", "enum": [ "free", "pro" ] } }, "required": [ "workspaceId", "workspaceName", "role", "scopes", "plan" ] }, "Token": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "examples": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Seconds.", "examples": [ 3600 ] }, "scope": { "type": "string", "description": "Space-separated, and never more than the credential was granted." } }, "required": [ "access_token", "token_type", "expires_in" ] }, "FlowSummary": { "type": "object", "description": "A flow without its tasks — what list endpoints return.", "properties": { "id": { "type": "string", "examples": [ "flw_2b8e10" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "dueDate": { "type": "string", "format": "date-time", "description": "The date the flow is meant to land, if one is set." }, "taskCount": { "type": "integer" }, "doneCount": { "type": "integer" }, "readyCount": { "type": "integer", "description": "Tasks that can be started right now." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "archived" ] }, "Flow": { "allOf": [ { "$ref": "#/components/schemas/FlowSummary" }, { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } }, "required": [ "tasks" ] } ], "description": "A flow with its full task graph and derived state." }, "Task": { "type": "object", "description": "A unit of work in a flow. Tasks are joined by dependencies: one is ready only when everything it depends on is done, and one with sub-tasks completes through them.", "properties": { "id": { "type": "string", "examples": [ "tsk_9f2c41" ] }, "flowId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "blocked", "ready", "in_progress", "done" ], "description": "Derived from the graph on read, never stored. Work moves ready → in_progress → done; nothing jumps straight to done." }, "dependsOn": { "type": "array", "items": { "type": "string" }, "description": "Task ids that must be done first." }, "blockedBy": { "type": "array", "items": { "type": "string" }, "description": "Of those, the ones not yet done. Empty when status is not \"blocked\"." }, "assigneeId": { "type": [ "string", "null" ] }, "estimateHours": { "type": [ "number", "null" ] }, "criticalPath": { "type": "boolean", "description": "True when this task is on the chain that decides the flow's finish date." }, "subtasks": { "type": "array", "items": { "$ref": "#/components/schemas/SubTask" } }, "requiredDeliverables": { "type": "array", "description": "Files that have to be handed in before the task can complete.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "satisfied": { "type": "boolean" } } } } }, "required": [ "id", "flowId", "name", "status", "dependsOn" ] }, "SubTask": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "done": { "type": "boolean" }, "assigneeId": { "type": [ "string", "null" ], "description": "Workspace member id." }, "estimateHours": { "type": [ "number", "null" ] } }, "required": [ "id", "name", "done" ] }, "WorkItem": { "type": "object", "description": "A task in the context of \"what should be worked on\", flattened so a caller does not have to hold the flow to make sense of it.", "properties": { "taskId": { "type": "string" }, "taskName": { "type": "string" }, "flowId": { "type": "string" }, "flowName": { "type": "string" }, "status": { "type": "string", "enum": [ "blocked", "ready", "in_progress", "done" ] }, "assigneeId": { "type": [ "string", "null" ] }, "estimateHours": { "type": [ "number", "null" ] }, "criticalPath": { "type": "boolean" }, "blockedBy": { "type": "array", "description": "On blocked work, the unfinished tasks holding it up, most-blocking first.", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "taskName": { "type": "string" }, "blocking": { "type": "integer", "description": "How many tasks this one is holding up." } } } } }, "required": [ "taskId", "taskName", "flowId", "flowName", "status" ] }, "Schedule": { "type": "object", "properties": { "flowId": { "type": "string" }, "dueDate": { "type": [ "string", "null" ], "description": "The day the flow is meant to land, `YYYY-MM-DD`." }, "projectedFinish": { "type": [ "string", "null" ], "description": "Working day it lands at the current shape and estimates, `YYYY-MM-DD`." }, "onTrack": { "type": [ "boolean", "null" ], "description": "Null when there is no due date to be on track against." }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleEntry" } } }, "required": [ "flowId", "entries" ] }, "ScheduleEntry": { "type": "object", "description": "One task on the critical-path pass. Dates are computed from estimates and dependencies; nothing here is stored.", "properties": { "taskId": { "type": "string" }, "taskName": { "type": "string" }, "earliestStart": { "type": "string", "description": "Working day, `YYYY-MM-DD`." }, "earliestFinish": { "type": "string", "description": "Working day, `YYYY-MM-DD`." }, "criticalPath": { "type": "boolean", "description": "On the chain that decides the finish date — no slack." }, "estimated": { "type": "boolean", "description": "False when the span is a one-day guess because nothing was estimated." } }, "required": [ "taskId", "taskName", "criticalPath" ] }, "Report": { "type": "object", "description": "The delivery health of a flow: what is done, what is left, what is holding it up, and who is carrying it.", "properties": { "flowId": { "type": "string" }, "flowName": { "type": "string" }, "completion": { "type": "number", "description": "0–1." }, "tasksTotal": { "type": "integer" }, "tasksDone": { "type": "integer" }, "tasksReady": { "type": "integer" }, "tasksBlocked": { "type": "integer" }, "hoursEstimated": { "type": [ "number", "null" ] }, "hoursRemaining": { "type": [ "number", "null" ] }, "unestimatedTasks": { "type": "array", "items": { "type": "string" }, "description": "Task ids with no estimate — the reason a projection is soft." }, "orphanedTasks": { "type": "array", "items": { "type": "string" }, "description": "Tasks nothing depends on and that depend on nothing." }, "workload": { "type": "array", "items": { "type": "object", "properties": { "memberId": { "type": "string" }, "name": { "type": "string" }, "openTasks": { "type": "integer" }, "hoursRemaining": { "type": [ "number", "null" ] } } } }, "topBlockers": { "type": "array", "items": { "type": "object", "properties": { "taskId": { "type": "string" }, "taskName": { "type": "string" }, "blocking": { "type": "integer" } } } } }, "required": [ "flowId", "completion", "tasksTotal" ] }, "Comment": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "authorId": { "type": "string" }, "authorName": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "taskId", "body", "createdAt" ] }, "Attachment": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "kind": { "type": "string", "enum": [ "reference", "deliverable" ] }, "uploadedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "kind" ] }, "Member": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } }, "required": [ "id", "email", "role" ] }, "Invite": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "role", "status" ] }, "Share": { "type": "object", "description": "A client or guest with access to one flow. Guests never occupy a seat.", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "viewer", "commenter" ] }, "flowId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "role", "flowId" ] }, "Template": { "type": "object", "description": "A saved flow shape, ready to start a new flow from.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "taskCount": { "type": "integer" }, "usedCount": { "type": "integer" } }, "required": [ "id", "name" ] }, "SearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "flow", "task", "template" ] }, "title": { "type": "string" }, "flowId": { "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Where it lives in the app, for a link back." } }, "required": [ "id", "type", "title" ] }, "NotificationPreferences": { "type": "object", "description": "What one person is emailed about, resolved. When `flowId` is set, this is the account settings with that flow's override already applied.", "properties": { "memberId": { "type": "string" }, "flowId": { "type": [ "string", "null" ], "description": "Null for the account-level answer." }, "email": { "type": "boolean", "description": "The master switch. False means no notification email at all, whatever the per-event flags say." }, "muted": { "type": "boolean", "description": "Set by a flow-level override to silence one flow." }, "events": { "type": "object", "description": "Per-event switches.", "properties": { "assigned": { "type": "boolean", "description": "A task was assigned to them." }, "unlocked": { "type": "boolean", "description": "A task of theirs stopped being blocked." }, "digest": { "type": "boolean", "description": "The morning summary. Account level only." } } }, "timezone": { "type": "string", "description": "IANA zone. The digest is sent in this person's morning.", "examples": [ "Europe/Paris" ] }, "digestHour": { "type": "integer", "description": "0–23, local." } }, "required": [ "memberId", "email", "events" ] }, "NotificationDelivery": { "type": "object", "description": "One email that was sent — or deliberately not sent, which is recorded too.", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "description": "`batch` (assignments and unblocked work, grouped) or `digest`." }, "status": { "type": "string", "description": "`sent`, `failed`, `skipped`, `skipped-empty`, or `claimed` while in flight." }, "sentAt": { "type": "string", "format": "date-time", "description": "When the send was claimed." }, "subject": { "type": [ "string", "null" ] }, "itemCount": { "type": "integer", "description": "How many events one batch covered. Notifications are batched after a quiet period, so this is usually more than one." }, "flowIds": { "type": "array", "items": { "type": "string" } }, "suppressed": { "type": "integer", "description": "Events dropped because the person had unsubscribed since they were queued." } }, "required": [ "id", "kind", "status" ] }, "NotificationDigest": { "type": "object", "description": "One person's day: what is on them, what is free to pick up, what moved. Spans every flow they can see, including flows shared with them from workspaces they are not a member of.", "properties": { "memberId": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time", "description": "When this was built." }, "wouldSend": { "type": "boolean", "description": "False when there is nothing worth mailing — an empty digest is never sent." }, "counts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Totals BEFORE the per-section caps, so a truncated list still reports honestly." }, "ready": { "type": "array", "items": { "type": "object", "properties": { "questId": { "type": "string", "description": "The flow id." }, "questName": { "type": "string" }, "nodeId": { "type": "string", "description": "The task id." }, "nodeTitle": { "type": "string" }, "hours": { "type": [ "number", "null" ] }, "criticalPath": { "type": "boolean" } } }, "description": "Assigned to them and unblocked." }, "inProgress": { "type": "array", "items": { "type": "object", "properties": { "questId": { "type": "string", "description": "The flow id." }, "questName": { "type": "string" }, "nodeId": { "type": "string", "description": "The task id." }, "nodeTitle": { "type": "string" }, "hours": { "type": [ "number", "null" ] }, "criticalPath": { "type": "boolean" } } } }, "blocked": { "type": "array", "items": { "type": "object", "properties": { "questId": { "type": "string", "description": "The flow id." }, "questName": { "type": "string" }, "nodeId": { "type": "string", "description": "The task id." }, "nodeTitle": { "type": "string" }, "hours": { "type": [ "number", "null" ] }, "criticalPath": { "type": "boolean" } } }, "description": "Theirs, waiting on someone else." }, "available": { "type": "array", "items": { "type": "object", "properties": { "questId": { "type": "string", "description": "The flow id." }, "questName": { "type": "string" }, "nodeId": { "type": "string", "description": "The task id." }, "nodeTitle": { "type": "string" }, "hours": { "type": [ "number", "null" ] }, "criticalPath": { "type": "boolean" } } }, "description": "Unassigned and ready — anyone could pick it up." }, "completed": { "type": "array", "items": { "type": "object" }, "description": "Finished in the last 24 hours, across their flows." }, "atRisk": { "type": "array", "items": { "type": "object" }, "description": "Flows projected to finish after their due date." } }, "required": [ "memberId", "wouldSend", "counts" ] } } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "paths": { "/v1/oauth/token": { "post": { "operationId": "auth.token", "summary": "Exchange client credentials for an access token", "description": "Standard OAuth 2.0 client-credentials grant (`application/x-www-form-urlencoded`). Credentials may also be sent as HTTP Basic. The token is a bearer token for this API and nothing else — it is not a planner session and cannot be used against the app.", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Must be `client_credentials`." }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "scope": { "type": "string", "description": "Space-separated. Defaults to everything the credential was granted; naming scopes here can only narrow it." } }, "required": [ "grant_type", "client_id", "client_secret" ] } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "description": "UNSUPPORTED_GRANT_TYPE · INVALID_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNSUPPORTED_GRANT_TYPE", "message": "Human-readable explanation." } } } } }, "401": { "description": "INVALID_CLIENT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_CLIENT", "message": "Human-readable explanation." } } } } } }, "security": [], "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST '{{API_URL}}/v1/oauth/token' \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'grant_type=client_credentials&client_id={{CLIENT_ID}}&client_secret={{CLIENT_SECRET}}'" } ], "x-examples": [ { "request": { "curl": "curl -X POST '{{API_URL}}/v1/oauth/token' \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'grant_type=client_credentials&client_id={{CLIENT_ID}}&client_secret={{CLIENT_SECRET}}'" }, "response": { "status": 200, "body": { "access_token": "fl_at_9c2f…", "token_type": "Bearer", "expires_in": 3600, "scope": "flows:read flows:write work:write" } } } ] } }, "/v1/oauth/revoke": { "post": { "operationId": "auth.revoke", "summary": "Revoke an access token", "description": "RFC 7009. Kills one issued token immediately. To kill the credential itself, delete it in the app — that also invalidates every token it ever issued.", "tags": [ "auth" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "SUCCESS — also returned for a token that was already invalid, per the RFC." }, "401": { "description": "INVALID_CLIENT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_CLIENT", "message": "Human-readable explanation." } } } } } }, "security": [] } }, "/v1/me": { "get": { "operationId": "workspace.context", "summary": "Who this credential is", "description": "The workspace, the credential's role and scopes, and the plan. Cheap, and the right health check for an integration.", "tags": [ "workspace" ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Context" } } } }, "401": { "description": "UNAUTHORIZED · CREDENTIAL_REVOKED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl '{{API_URL}}/v1/me' \\\n -H 'Authorization: Bearer {{API_KEY}}'" } ], "x-examples": [ { "request": { "curl": "curl '{{API_URL}}/v1/me' \\\n -H 'Authorization: Bearer {{API_KEY}}'" }, "response": { "status": 200, "body": { "workspaceId": "org_5c1", "workspaceName": "Acme Studio", "credentialId": "key_8fd2", "credentialName": "Acme CI", "role": "member", "scopes": [ "flows:read", "flows:write", "work:write" ], "plan": "pro" } } } ] } }, "/v1/team/members": { "get": { "operationId": "team.members", "summary": "List members", "description": "People in the workspace and their roles. Guests are not members and are not listed here — they belong to a flow (see `/v1/flows/{flowId}/shares`).", "tags": [ "team" ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "team:read" ] } ] } }, "/v1/team/invites": { "get": { "operationId": "team.invites.list", "summary": "List pending invitations", "tags": [ "team" ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "team:read" ] } ] }, "post": { "operationId": "team.invites.create", "summary": "Invite someone", "description": "Sends an invitation. A pending invite occupies a seat for the purposes of the plan limit, which is why this can be refused on a full workspace before anyone has accepted.", "tags": [ "team" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "description": "`admin`, `member` or `viewer`.", "default": "member" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "400": { "description": "INVALID_EMAIL · ALREADY_MEMBER", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_EMAIL", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_LIMIT_REACHED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "team:write" ] } ], "x-minRole": "admin" } }, "/v1/team/members/{memberId}": { "patch": { "operationId": "team.members.role", "summary": "Change a member's role", "tags": [ "team" ], "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "`admin`, `member` or `viewer`." } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "team:write" ] } ], "x-minRole": "admin" } }, "/v1/templates": { "get": { "operationId": "templates.list", "summary": "List templates", "description": "Saved flow shapes in this workspace.", "tags": [ "templates" ], "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "templates:read" ] } ] } }, "/v1/templates/{templateId}": { "get": { "operationId": "templates.get", "summary": "Get a template", "description": "The template with the task graph it will produce, so an integration can show what it is about to create.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "templates:read" ] } ] } }, "/v1/templates/{templateId}/flows": { "post": { "operationId": "templates.use", "summary": "Start a flow from a template", "description": "Creates a new flow from the template and returns it, graph and all. Using a template is available on every plan; saving new ones is not.", "tags": [ "templates" ], "parameters": [ { "name": "templateId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Defaults to the template's name." }, "dueDate": { "type": "string", "description": "ISO 8601." } } } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · SUBSCRIPTION_PAST_DUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write", "templates:read" ] } ], "x-minRole": "member" } }, "/v1/search": { "get": { "operationId": "search", "summary": "Search the workspace", "description": "Flows, tasks and templates matching a query — for a picker, or to resolve a name a human typed into an id.", "tags": [ "search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "`flow`, `task` or `template`. Omit for all three.", "schema": { "type": "string", "description": "`flow`, `task` or `template`. Omit for all three." } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "total", "items" ] } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/flows": { "get": { "operationId": "flows.list", "summary": "List flows", "description": "Flows in the workspace, newest first. Archived flows are excluded unless `archived=true`.", "tags": [ "flows" ], "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "Return archived flows instead of live ones.", "schema": { "type": "boolean", "description": "Return archived flows instead of live ones.", "default": false } }, { "name": "q", "in": "query", "required": false, "description": "Match on flow name.", "schema": { "type": "string", "description": "Match on flow name." } }, { "name": "size", "in": "query", "required": false, "description": "Page size, 1–100.", "schema": { "type": "integer", "description": "Page size, 1–100.", "default": 25 } }, { "name": "from", "in": "query", "required": false, "description": "Offset.", "schema": { "type": "integer", "description": "Offset.", "default": 0 } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FlowSummary" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PLAN_REQUIRED", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl '{{API_URL}}/v1/flows?size=2' \\\n -H 'Authorization: Bearer {{API_KEY}}'" } ], "x-examples": [ { "request": { "curl": "curl '{{API_URL}}/v1/flows?size=2' \\\n -H 'Authorization: Bearer {{API_KEY}}'" }, "response": { "status": 200, "body": { "total": 2, "items": [ { "id": "flw_2b8e10", "name": "Acme: Website relaunch", "archived": false, "taskCount": 14, "doneCount": 6, "readyCount": 2, "dueDate": "2026-09-14T00:00:00.000Z" }, { "id": "flw_77a301", "name": "Northwind: Brand refresh", "archived": false, "taskCount": 9, "doneCount": 9, "readyCount": 0, "dueDate": null } ] } } } ] }, "post": { "operationId": "flows.create", "summary": "Create a flow", "description": "Creates a flow and, optionally, its whole task graph in one call. A task's `after` references other tasks **by index in this request**, so the dependency chain arrives with the flow rather than in follow-up calls. Cycles are refused outright.", "tags": [ "flows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "dueDate": { "type": "string", "description": "ISO 8601. Used by the schedule and report endpoints to answer \"is this on track\"." }, "tasks": { "type": "array", "items": { "type": "TaskInput" }, "description": "Tasks to create, in order. Each: `{ name, description?, estimateHours?, assigneeId?, after?: [index] }`, where `after` holds indexes into this same array." } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "400": { "description": "VALIDATION_FAILED · CIRCULAR_DEPENDENCY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · SUBSCRIPTION_PAST_DUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST '{{API_URL}}/v1/flows' \\\n -H 'Authorization: Bearer {{API_KEY}}' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"Acme: Website relaunch\",\"dueDate\":\"2026-09-14\",\"tasks\":[{\"name\":\"Brief\"},{\"name\":\"Design\",\"after\":[0]},{\"name\":\"Client approval\",\"after\":[1]}]}'" } ], "x-examples": [ { "request": { "curl": "curl -X POST '{{API_URL}}/v1/flows' \\\n -H 'Authorization: Bearer {{API_KEY}}' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"Acme: Website relaunch\",\"dueDate\":\"2026-09-14\",\"tasks\":[{\"name\":\"Brief\"},{\"name\":\"Design\",\"after\":[0]},{\"name\":\"Client approval\",\"after\":[1]}]}'" }, "response": { "status": 201, "body": { "id": "flw_2b8e10", "name": "Acme: Website relaunch", "archived": false, "dueDate": "2026-09-14T00:00:00.000Z", "tasks": [ { "id": "tsk_1", "flowId": "flw_2b8e10", "name": "Brief", "status": "ready", "dependsOn": [], "blockedBy": [] }, { "id": "tsk_2", "flowId": "flw_2b8e10", "name": "Design", "status": "blocked", "dependsOn": [ "tsk_1" ], "blockedBy": [ "tsk_1" ] }, { "id": "tsk_3", "flowId": "flw_2b8e10", "name": "Client approval", "status": "blocked", "dependsOn": [ "tsk_2" ], "blockedBy": [ "tsk_2" ] } ] } } } ] } }, "/v1/flows/{flowId}": { "get": { "operationId": "flows.get", "summary": "Get a flow", "description": "The flow with its full task graph and derived state — status, what is blocking what, and which tasks are on the critical path.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "description": "Flow id.", "schema": { "type": "string", "description": "Flow id." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flow" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] }, "patch": { "operationId": "flows.update", "summary": "Update a flow", "description": "Changes the flow itself. Tasks are edited through the task endpoints.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "dueDate": { "type": "string", "description": "ISO 8601, or null to clear it." } } } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowSummary" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · SUBSCRIPTION_PAST_DUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" }, "delete": { "operationId": "flows.archive", "summary": "Archive a flow", "description": "Archives rather than destroys: the flow leaves the list and can be restored. Nothing in Flowral deletes client history on a single call.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "ARCHIVED" }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · SUBSCRIPTION_PAST_DUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/flows/{flowId}/restore": { "post": { "operationId": "flows.restore", "summary": "Restore an archived flow", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowSummary" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND · NOT_ARCHIVED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/flows/{flowId}/schedule": { "get": { "operationId": "flows.schedule", "summary": "Get the schedule", "description": "Runs the critical-path pass: earliest and latest start and finish per task, slack, and the projected finish for the flow. Computed from estimates and dependencies — no dates are stored, so this is always current.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": false, "description": "ISO 8601. Defaults to today.", "schema": { "type": "string", "description": "ISO 8601. Defaults to today." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/flows/{flowId}/report": { "get": { "operationId": "flows.report", "summary": "Get the delivery report", "description": "Completion, effort remaining, workload per member, the tasks blocking the most work, and what is unestimated or orphaned. The same figures the Reporting view shows.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/flows/{flowId}/exports": { "post": { "operationId": "flows.export", "summary": "Export a flow", "description": "Renders the flow through the same pipeline the app uses. `pdf` is the delivery document (diagram plus execution plan); `png` is the dependency diagram on its own. Responds with the bytes, `Content-Disposition` set.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "description": "`pdf` or `png`.", "default": "pdf" } }, "required": [ "format" ] } } } }, "responses": { "200": { "description": "SUCCESS — `application/pdf` or `image/png`.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } }, "502": { "description": "RENDER_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RENDER_FAILED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/flows/{flowId}/shares": { "get": { "operationId": "flows.shares.list", "summary": "List a flow's guests", "description": "Clients and guests with access to this flow. Guests never occupy a seat, on any plan.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Share" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] }, "post": { "operationId": "flows.shares.create", "summary": "Share a flow with a guest", "description": "Gives one person access to this flow only — they see its progress and nothing else in the workspace.", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string", "description": "`viewer` or `commenter`.", "default": "viewer" } }, "required": [ "email" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Share" } } } }, "400": { "description": "INVALID_EMAIL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "INVALID_EMAIL", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/flows/{flowId}/shares/{shareId}": { "delete": { "operationId": "flows.shares.remove", "summary": "Remove a guest from a flow", "tags": [ "flows" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "REMOVED" }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/flows/{flowId}/tasks": { "get": { "operationId": "tasks.list", "summary": "List a flow's tasks", "description": "Every task in the flow with its derived status. Filter by `status` to get just what is ready, or just what is blocked.", "tags": [ "tasks" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "`blocked`, `ready`, `in_progress` or `done`.", "schema": { "type": "string", "description": "`blocked`, `ready`, `in_progress` or `done`." } }, { "name": "assigneeId", "in": "query", "required": false, "description": "Only tasks assigned to this member.", "schema": { "type": "string", "description": "Only tasks assigned to this member." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] }, "post": { "operationId": "tasks.create", "summary": "Add a task to a flow", "description": "Creates a task and links it in the same call. `after` are the tasks that must finish first; `before` are the tasks that now wait on this one — use it to insert a step into an existing chain.", "tags": [ "tasks" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "after": { "type": "array", "items": { "type": "string" }, "description": "Task ids this depends on." }, "before": { "type": "array", "items": { "type": "string" }, "description": "Task ids that should depend on this." }, "estimateHours": { "type": "number" }, "assigneeId": { "type": "string" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "VALIDATION_FAILED · CIRCULAR_DEPENDENCY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · SUBSCRIPTION_PAST_DUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}": { "get": { "operationId": "tasks.get", "summary": "Get a task", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] }, "patch": { "operationId": "tasks.update", "summary": "Update a task", "description": "Name, description and estimate. Status is not settable here — see the transition endpoints. Refused once work has started, the same rule the canvas applies.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "estimateHours": { "type": "number" } } } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · SUBSCRIPTION_PAST_DUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" }, "delete": { "operationId": "tasks.delete", "summary": "Delete a task", "description": "Bridges the gap it leaves: whatever depended on this task now depends on what it depended on, so removing a step from the middle leaves a plan that still runs end to end.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "DELETED" }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · SUBSCRIPTION_PAST_DUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/subtasks": { "post": { "operationId": "tasks.subtasks.create", "summary": "Add a sub-task", "description": "A breakdown of one task. A task that has sub-tasks completes through them rather than directly.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "assigneeId": { "type": "string" }, "estimateHours": { "type": "number" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubTask" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/dependencies": { "post": { "operationId": "tasks.dependencies.add", "summary": "Add a dependency", "description": "Makes this task wait on another. Refuses anything that would create a cycle.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dependsOn": { "type": "string", "description": "The task that must finish first." } }, "required": [ "dependsOn" ] } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "CIRCULAR_DEPENDENCY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CIRCULAR_DEPENDENCY", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/dependencies/{dependsOnId}": { "delete": { "operationId": "tasks.dependencies.remove", "summary": "Remove a dependency", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "dependsOnId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/start": { "post": { "operationId": "tasks.start", "summary": "Start a task", "description": "Ready → in progress. Refused while anything it depends on is unfinished, and assigned work only moves for its assignee.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "409": { "description": "TASK_BLOCKED · ALREADY_DONE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "TASK_BLOCKED", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "work:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/complete": { "post": { "operationId": "tasks.complete", "summary": "Complete a task", "description": "In progress → done, and the response says what that unblocked — which is the next question every time. Refused if sub-tasks are outstanding or a required deliverable has not been handed in.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "type": "string", "description": "Optional note recorded on the completion." } } } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "example": { "task": { "id": "tsk_2", "name": "Design", "status": "done", "criticalPath": true }, "unblocked": [ { "id": "tsk_3", "name": "Client approval", "status": "ready" } ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "409": { "description": "TASK_BLOCKED · SUBTASKS_OUTSTANDING · DELIVERABLE_REQUIRED · ALREADY_DONE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "TASK_BLOCKED", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "work:write" ] } ], "x-minRole": "member", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X POST '{{API_URL}}/v1/tasks/tsk_2/complete' \\\n -H 'Authorization: Bearer {{API_KEY}}'" } ], "x-examples": [ { "request": { "curl": "curl -X POST '{{API_URL}}/v1/tasks/tsk_2/complete' \\\n -H 'Authorization: Bearer {{API_KEY}}'" }, "response": { "status": 200, "body": { "task": { "id": "tsk_2", "name": "Design", "status": "done", "criticalPath": true }, "unblocked": [ { "id": "tsk_3", "name": "Client approval", "status": "ready" } ] } } } ] } }, "/v1/tasks/{taskId}/reopen": { "post": { "operationId": "tasks.reopen", "summary": "Reopen a task", "description": "Done → in progress. Refused once anything downstream has been started: undoing a completion that the next person already acted on would rewrite work that is under way.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "409": { "description": "DOWNSTREAM_STARTED · NOT_DONE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "DOWNSTREAM_STARTED", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "work:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/assignee": { "put": { "operationId": "tasks.assign", "summary": "Assign a task", "description": "Sets the owner. Send `null` to unassign.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "assigneeId": { "type": "string", "description": "Member id, or null." } } } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND · MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "work:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/comments": { "get": { "operationId": "tasks.comments.list", "summary": "List comments", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] }, "post": { "operationId": "tasks.comments.create", "summary": "Comment on a task", "description": "The one write a viewer credential can make, and the one that is never frozen by work having started.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string" } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "work:write" ] } ] } }, "/v1/tasks/{taskId}/attachments": { "post": { "operationId": "tasks.attachments.create", "summary": "Attach a file", "description": "A reference file on the task — a brief, a spec, a screenshot. `multipart/form-data`.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Images, video, PDF and Word, up to 50 MB." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "MISSING_FILE · FILE_TOO_LARGE · UNSUPPORTED_FILE_TYPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "MISSING_FILE", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:write" ] } ], "x-minRole": "member" } }, "/v1/tasks/{taskId}/deliverables": { "post": { "operationId": "tasks.deliverables.submit", "summary": "Hand in a deliverable", "description": "Satisfies a file requirement on the task, which is what lets it complete. Different from an attachment: this one is the thing being asked for.", "tags": [ "tasks" ], "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "requirementId": { "type": "string", "description": "Which requirement this satisfies. Optional when the task has exactly one." } }, "required": [ "file" ] } } } }, "responses": { "201": { "description": "CREATED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "MISSING_FILE · FILE_TOO_LARGE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "MISSING_FILE", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND · REQUIREMENT_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "work:write" ] } ] } }, "/v1/work/available": { "get": { "operationId": "work.available", "summary": "What is ready to start", "description": "Every unblocked, unstarted task across the workspace, critical-path work first. The single most useful call in this API.", "tags": [ "work" ], "parameters": [ { "name": "flowId", "in": "query", "required": false, "description": "Restrict to one flow.", "schema": { "type": "string", "description": "Restrict to one flow." } }, { "name": "assigneeId", "in": "query", "required": false, "description": "Restrict to one person. Unassigned work is always included.", "schema": { "type": "string", "description": "Restrict to one person. Unassigned work is always included." } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkItem" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "PLAN_REQUIRED", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl '{{API_URL}}/v1/work/available' \\\n -H 'Authorization: Bearer {{API_KEY}}'" } ], "x-examples": [ { "request": { "curl": "curl '{{API_URL}}/v1/work/available' \\\n -H 'Authorization: Bearer {{API_KEY}}'" }, "response": { "status": 200, "body": { "total": 2, "items": [ { "taskId": "tsk_3", "taskName": "Client approval", "flowId": "flw_2b8e10", "flowName": "Acme: Website relaunch", "status": "ready", "assigneeId": null, "criticalPath": true }, { "taskId": "tsk_9", "taskName": "Write launch copy", "flowId": "flw_2b8e10", "flowName": "Acme: Website relaunch", "status": "ready", "assigneeId": "usr_41", "criticalPath": false } ] } } } ] } }, "/v1/work/mine": { "get": { "operationId": "work.mine", "summary": "What is assigned to the caller", "description": "Ready and in-progress work assigned to this credential's identity. For a service credential, pass `assigneeId` to `/work/available` instead — a credential is not a person and has nothing assigned to it.", "tags": [ "work" ], "parameters": [ { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkItem" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/work/blocked": { "get": { "operationId": "work.blocked", "summary": "What is stuck, and on what", "description": "Blocked work with the unfinished tasks holding it up, ranked so the task blocking the most appears first. This is the \"where is delivery actually stalling\" call.", "tags": [ "work" ], "parameters": [ { "name": "flowId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkItem" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/work/in-progress": { "get": { "operationId": "work.inProgress", "summary": "What is under way", "tags": [ "work" ], "parameters": [ { "name": "flowId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "assigneeId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkItem" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/work/overview": { "get": { "operationId": "work.overview", "summary": "The whole workspace in one call", "description": "Per-flow counts, workload per member and the flows at risk of their due date — so a dashboard does not have to fetch twelve flows to render.", "tags": [ "work" ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "example": { "flows": [ { "flowId": "flw_2b8e10", "flowName": "Acme: Website relaunch", "completion": 0.43, "ready": 2, "blocked": 6, "inProgress": 1, "dueDate": "2026-09-14T00:00:00.000Z", "onTrack": true } ], "workload": [ { "memberId": "usr_41", "name": "Alex", "openTasks": 5, "hoursRemaining": 22 } ], "atRisk": [] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "flows:read" ] } ] } }, "/v1/notifications/preferences": { "get": { "operationId": "notifications.preferences.get", "summary": "What a person is subscribed to", "description": "The settings that actually apply, after the account defaults and any flow overrides have been resolved. This is the answer, not the stored row — a `true` here means mail will be sent.", "tags": [ "notifications" ], "parameters": [ { "name": "memberId", "in": "query", "required": true, "description": "The person these settings belong to. A credential has no inbox, so this is never optional.", "schema": { "type": "string", "description": "The person these settings belong to. A credential has no inbox, so this is never optional." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "MEMBER_NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "notifications:read" ] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl '{{API_URL}}/v1/notifications/preferences?memberId=usr_41' \\\n -H 'Authorization: Bearer {{API_KEY}}'" } ], "x-examples": [ { "request": { "curl": "curl '{{API_URL}}/v1/notifications/preferences?memberId=usr_41' \\\n -H 'Authorization: Bearer {{API_KEY}}'" }, "response": { "status": 200, "body": { "memberId": "usr_41", "flowId": null, "email": true, "muted": false, "events": { "assigned": true, "unlocked": true, "digest": true }, "timezone": "Europe/Paris", "digestHour": 8 } } } ] }, "put": { "operationId": "notifications.preferences.set", "summary": "Change what a person is subscribed to", "description": "Sets the account defaults. Only the keys you send are changed; sending `null` for one resets it to the built-in default rather than turning it off.", "tags": [ "notifications" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "description": "The person these settings belong to." }, "email": { "type": "boolean", "description": "The master switch for this scope. `null` means \"inherit\"." }, "muted": { "type": "boolean", "description": "Flow scope only: silence everything about this flow." }, "events": { "type": "object", "description": "Per-event switches: `assigned`, `unlocked`, `digest`. Omit a key to leave it alone; send `null` to reset it to inherited." }, "timezone": { "type": "string", "description": "Account scope only. IANA zone name — the digest is sent in this person's morning, not the server's." }, "digestHour": { "type": "integer", "description": "Account scope only. 0–23, local. Default 8." } }, "required": [ "memberId" ] } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "MEMBER_NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "notifications:write" ] } ], "x-minRole": "admin", "x-codeSamples": [ { "lang": "cURL", "source": "curl -X PUT '{{API_URL}}/v1/notifications/preferences' \\\n -H 'Authorization: Bearer {{API_KEY}}' \\\n -H 'Content-Type: application/json' \\\n -d '{\"memberId\":\"usr_41\",\"timezone\":\"America/New_York\",\"digestHour\":7}'" } ], "x-examples": [ { "request": { "curl": "curl -X PUT '{{API_URL}}/v1/notifications/preferences' \\\n -H 'Authorization: Bearer {{API_KEY}}' \\\n -H 'Content-Type: application/json' \\\n -d '{\"memberId\":\"usr_41\",\"timezone\":\"America/New_York\",\"digestHour\":7}'" }, "response": { "status": 200, "body": { "memberId": "usr_41", "flowId": null, "email": true, "muted": false, "events": { "assigned": true, "unlocked": true, "digest": true }, "timezone": "America/New_York", "digestHour": 7 } } } ] } }, "/v1/notifications/preferences/flows/{flowId}": { "get": { "operationId": "notifications.preferences.flow.get", "summary": "What a person is subscribed to on one flow", "description": "The account settings with this flow's override applied.", "tags": [ "notifications" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memberId", "in": "query", "required": true, "description": "The person these settings belong to. A credential has no inbox, so this is never optional.", "schema": { "type": "string", "description": "The person these settings belong to. A credential has no inbox, so this is never optional." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND · MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "notifications:read" ] } ] }, "put": { "operationId": "notifications.preferences.flow.set", "summary": "Override a person's settings for one flow", "description": "The usual use is `{\"muted\": true}` — silence one noisy flow without touching anything else this person gets.", "tags": [ "notifications" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "memberId": { "type": "string", "description": "The person these settings belong to." }, "email": { "type": "boolean", "description": "The master switch for this scope. `null` means \"inherit\"." }, "muted": { "type": "boolean", "description": "Flow scope only: silence everything about this flow." }, "events": { "type": "object", "description": "Per-event switches: `assigned`, `unlocked`, `digest`. Omit a key to leave it alone; send `null` to reset it to inherited." }, "timezone": { "type": "string", "description": "Account scope only. IANA zone name — the digest is sent in this person's morning, not the server's." }, "digestHour": { "type": "integer", "description": "Account scope only. 0–23, local. Default 8." } }, "required": [ "memberId" ] } } } }, "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "VALIDATION_FAILED", "message": "Human-readable explanation." } } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND · MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "notifications:write" ] } ], "x-minRole": "admin" }, "delete": { "operationId": "notifications.preferences.flow.clear", "summary": "Remove a flow override", "description": "The flow follows the person's account settings again. Not the same as turning everything off for it.", "tags": [ "notifications" ], "parameters": [ { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "memberId", "in": "query", "required": true, "description": "The person these settings belong to. A credential has no inbox, so this is never optional.", "schema": { "type": "string", "description": "The person these settings belong to. A credential has no inbox, so this is never optional." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferences" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "NOT_FOUND · MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "notifications:write" ] } ], "x-minRole": "admin" } }, "/v1/notifications/log": { "get": { "operationId": "notifications.log", "summary": "What was actually sent", "description": "One row per email that left the building, newest first — batches and digests alike. Use it to answer \"did they get told\", and to see what was suppressed because they had unsubscribed.", "tags": [ "notifications" ], "parameters": [ { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 25 } }, { "name": "memberId", "in": "query", "required": true, "description": "The person these settings belong to. A credential has no inbox, so this is never optional.", "schema": { "type": "string", "description": "The person these settings belong to. A credential has no inbox, so this is never optional." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total matching, not the length of `items`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationDelivery" } } }, "required": [ "total", "items" ] } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "MEMBER_NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "notifications:read" ] } ] } }, "/v1/notifications/digest": { "get": { "operationId": "notifications.digest.preview", "summary": "This person's digest, without sending it", "description": "What tomorrow morning's mail would say, built by the real builder and delivered to nobody. Also the cleanest per-person view of \"what should I work on today\" across every flow they can see — `/v1/work/available` answers that per workspace, this answers it per person.", "tags": [ "notifications" ], "parameters": [ { "name": "memberId", "in": "query", "required": true, "description": "The person these settings belong to. A credential has no inbox, so this is never optional.", "schema": { "type": "string", "description": "The person these settings belong to. A credential has no inbox, so this is never optional." } } ], "responses": { "200": { "description": "SUCCESS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationDigest" } } } }, "401": { "description": "UNAUTHORIZED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Human-readable explanation." } } } } }, "403": { "description": "FORBIDDEN · PLAN_REQUIRED · INSUFFICIENT_SCOPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "FORBIDDEN", "message": "Human-readable explanation." } } } } }, "404": { "description": "MEMBER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "MEMBER_NOT_FOUND", "message": "Human-readable explanation." } } } } }, "429": { "description": "RATE_LIMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Human-readable explanation." } } } } } }, "security": [ { "apiKey": [] }, { "oauth2": [ "notifications:read" ] } ], "x-codeSamples": [ { "lang": "cURL", "source": "curl '{{API_URL}}/v1/notifications/digest?memberId=usr_41' \\\n -H 'Authorization: Bearer {{API_KEY}}'" } ], "x-examples": [ { "request": { "curl": "curl '{{API_URL}}/v1/notifications/digest?memberId=usr_41' \\\n -H 'Authorization: Bearer {{API_KEY}}'" }, "response": { "status": 200, "body": { "memberId": "usr_41", "wouldSend": true, "counts": { "ready": 2, "inProgress": 1, "blocked": 1, "available": 3, "doneByMe": 1, "doneByTeam": 4, "atRisk": 1, "flows": 3 }, "ready": [ { "questId": "flw_2b8e10", "questName": "Acme: Website relaunch", "nodeId": "tsk_9", "nodeTitle": "Write launch copy", "hours": 8, "criticalPath": true } ], "atRisk": [ { "questId": "flw_2b8e10", "questName": "Acme: Website relaunch", "dueDate": "2026-09-14", "projectedFinish": "2026-09-21", "workdaysOver": 5 } ] } } } ] } } } }