{"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":"brainstorms","description":"Idea-tree boards, and the ideas on them."},{"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"},"public":{"type":"boolean","description":"Whether this flow is published — readable by anyone with its link, with no account. Assignees, comments and files are never included in the public view."},"publicUrl":{"type":["string","null"],"description":"The published link, or null when the flow is private.","examples":["https://platform.flowral.app/public/flow/flw_2b8e10"]},"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"},"parentId":{"type":["string","null"],"description":"Set when this is a sub-task — the objective it belongs to. Null for an objective itself."},"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","parentId","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"},"subtasks":{"type":"array","description":"This objective's sub-tasks, if it has any. An objective with sub-tasks completes through them rather than directly — see the Task schema — so a client offering \"start\"/\"complete\" on this item should check here first.","items":{"$ref":"#/components/schemas/SubTask"}},"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","subtasks"]},"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"]},"BrainstormSummary":{"type":"object","description":"A brainstorm without its ideas — what list endpoints return.","properties":{"id":{"type":"string","examples":["brn_4f0a12"]},"name":{"type":"string"},"archived":{"type":"boolean"},"public":{"type":"boolean","description":"Whether this brainstorm is published — readable by anyone with its link, with no account."},"publicUrl":{"type":["string","null"],"description":"The published link, or null when private."},"ideaCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","archived"]},"Brainstorm":{"allOf":[{"$ref":"#/components/schemas/BrainstormSummary"},{"type":"object","properties":{"ideas":{"type":"array","items":{"$ref":"#/components/schemas/Idea"}}},"required":["ideas"]}],"description":"A brainstorm with every idea on its board."},"Idea":{"type":"object","description":"One box on a brainstorm board.","properties":{"id":{"type":"string","examples":["idea_7c1b90"]},"brainstormId":{"type":"string"},"parentId":{"type":["string","null"],"description":"The idea this nests under, or null for a root idea."},"title":{"type":"string"},"notes":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"assigneeId":{"type":["string","null"]},"commentCount":{"type":"integer"},"fileCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","brainstormId","title"]},"IdeaComment":{"type":"object","properties":{"id":{"type":"string"},"ideaId":{"type":"string"},"authorId":{"type":"string"},"authorName":{"type":"string"},"body":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","ideaId","body","createdAt"]},"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/authorize":{"get":{"operationId":"auth.authorize","summary":"Start a first-party sign-in (authorization code + PKCE)","description":"Browser-facing, not meant to be called by anything but a user-agent. Validates the request and redirects to the Flowral app's own sign-in screen; once the person signs in and allows the connection there, the app redirects on to `redirect_uri` with a one-time `code`. POST /oauth/token's `authorization_code` grant exchanges it for a token. `client_id` must name a registered first-party client (currently `flowral-vscode`) and `redirect_uri` must be a loopback address it owns.","tags":["auth"],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"description":"A loopback address, e.g. `http://127.0.0.1:<port>/callback`.","schema":{"type":"string","description":"A loopback address, e.g. `http://127.0.0.1:<port>/callback`."}},{"name":"response_type","in":"query","required":true,"description":"Must be `code`.","schema":{"type":"string","description":"Must be `code`."}},{"name":"code_challenge","in":"query","required":true,"description":"PKCE, S256 of a code_verifier the client keeps.","schema":{"type":"string","description":"PKCE, S256 of a code_verifier the client keeps."}},{"name":"code_challenge_method","in":"query","required":true,"description":"Must be `S256`.","schema":{"type":"string","description":"Must be `S256`."}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"description":"Space-separated. Defaults to everything the signed-in person can do; naming scopes here can only narrow it.","schema":{"type":"string","description":"Space-separated. Defaults to everything the signed-in person can do; naming scopes here can only narrow it."}}],"responses":{"302":{"description":"Redirects to the app's sign-in screen."}},"security":[]}},"/v1/oauth/token":{"post":{"operationId":"auth.token","summary":"Exchange credentials for an access token","description":"Three grants, all `application/x-www-form-urlencoded`:\n\n- `client_credentials` — a workspace credential's id/secret. May also be sent as HTTP Basic.\n- `authorization_code` — the code from `/oauth/authorize`, with the PKCE `code_verifier`. Issues a token that acts as the person who signed in, not a workspace credential — plus a `refresh_token`, since a person has no secret to silently re-present an hour later.\n- `refresh_token` — trades the refresh token from an `authorization_code` grant for a new access/refresh pair. Rotated: the old refresh token stops working the moment this succeeds. Pass `org_id` to move to a DIFFERENT workspace the same person belongs to, without a second trip through the browser — checked fresh against live membership, same as a new sign-in would be.\n\nEither way 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":"`client_credentials`, `authorization_code`, or `refresh_token`."},"client_id":{"type":"string","description":"Required for client_credentials and authorization_code."},"client_secret":{"type":"string","description":"client_credentials only."},"code":{"type":"string","description":"authorization_code only — from /oauth/authorize."},"code_verifier":{"type":"string","description":"authorization_code only — PKCE."},"redirect_uri":{"type":"string","description":"authorization_code only — must match the value sent to /oauth/authorize."},"refresh_token":{"type":"string","description":"refresh_token only."},"org_id":{"type":"string","description":"refresh_token only. Switch to a different workspace the person belongs to; omit to just refresh the current one."},"scope":{"type":"string","description":"Space-separated. Defaults to everything the credential (or, for authorization_code, the person) was granted; naming scopes here can only narrow it."}},"required":["grant_type"]}}}},"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}}},"400":{"description":"UNSUPPORTED_GRANT_TYPE · INVALID_SCOPE · invalid_grant · invalid_request","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."}}}}},"403":{"description":"invalid_target","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_target","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. For a person-token (authorization_code), also includes `userId` — the same id `GET /team/members` lists them under, for a client that wants \"assign to me\"/\"my work\" to work without asking the person to pick themselves out of their own team — and `orgs`: every workspace they belong to, for a client that wants to offer a \"switch workspace\" action (see POST /oauth/token's refresh_token grant). Unlike every other /v1 route, this one is NOT refused on a Free-plan workspace — it reports `plan: \"free\"` truthfully instead, which is what lets a client explain the refusal (or, for a person-token, offer switching to a different workspace) rather than just receiving one.","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":"object"},"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}/publish":{"post":{"operationId":"flows.publish","summary":"Publish a flow","description":"Makes the flow readable by anyone with its link, with no account and nothing to accept. The public view never includes assignees, comments, uploaded files or task notes, and its items cannot be opened. Returns the flow, including its publicUrl.","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","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.unpublish","summary":"Un-publish a flow","description":"Takes the flow off the internet. Immediate and total: the link stops working for everyone who already has it, including anyone with the page open. Embeds of it go dark at the same moment.","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","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}]}}}]}},"/v1/brainstorms":{"get":{"operationId":"brainstorms.list","summary":"List brainstorms","description":"Brainstorms in the workspace, newest first. Archived ones are excluded unless `archived=true`.","tags":["brainstorms"],"parameters":[{"name":"archived","in":"query","required":false,"description":"Return archived brainstorms instead of live ones.","schema":{"type":"boolean","description":"Return archived brainstorms instead of live ones.","default":false}},{"name":"q","in":"query","required":false,"description":"Match on brainstorm name.","schema":{"type":"string","description":"Match on brainstorm 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/BrainstormSummary"}}},"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"]}]},"post":{"operationId":"brainstorms.create","summary":"Create a brainstorm","description":"Creates a brainstorm and, optionally, its whole starting idea tree in one call. An idea's `parent` references another idea **by index in this request**, so a shape arrives with the board rather than in follow-up calls.","tags":["brainstorms"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"ideas":{"type":"array","items":{"type":"object"},"description":"Ideas to create, in order. Each: `{ title, notes?, parent?: index }`, where `parent` is an index into this same array — omit it for a root idea."}},"required":["name"]}}}},"responses":{"201":{"description":"CREATED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brainstorm"}}}},"400":{"description":"VALIDATION_FAILED · INVALID_BOX_TREE","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"}},"/v1/brainstorms/archived":{"get":{"operationId":"brainstorms.archived","summary":"List the archive","description":"This workspace's archived brainstorms, most recently deleted first. Requires an owner or admin role, same as the app's archive view.","tags":["brainstorms"],"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/BrainstormSummary"}}},"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","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"]}],"x-minRole":"admin"}},"/v1/brainstorms/{brainstormId}":{"get":{"operationId":"brainstorms.get","summary":"Get a brainstorm","description":"The brainstorm with every idea on its board.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brainstorm"}}}},"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":"brainstorms.update","summary":"Rename a brainstorm","description":"Ideas are edited through the idea endpoints.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrainstormSummary"}}}},"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":"brainstorms.archive","summary":"Archive a brainstorm","description":"Archives rather than destroys, so it can be restored — with one exception, same rule the app applies: a brainstorm with no ideas on it yet is deleted outright, since there is nothing in it to recover.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"ARCHIVED (or deleted outright, if it had no ideas)"},"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/brainstorms/{brainstormId}/restore":{"post":{"operationId":"brainstorms.restore","summary":"Restore an archived brainstorm","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrainstormSummary"}}}},"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":"admin"}},"/v1/brainstorms/{brainstormId}/shares":{"get":{"operationId":"brainstorms.shares.list","summary":"List a brainstorm's guests","tags":["brainstorms"],"parameters":[{"name":"brainstormId","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":"brainstorms.shares.create","summary":"Share a brainstorm with a guest","description":"Gives one person access to this brainstorm only — they see it from their own workspace and never join the squad. Only existing Flowral accounts can be shared with this way; the API does not send invitation emails.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"role":{"type":"string","description":"`editor` or `viewer`.","default":"editor"}},"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/brainstorms/{brainstormId}/shares/{shareId}":{"delete":{"operationId":"brainstorms.shares.remove","summary":"Remove a guest from a brainstorm","tags":["brainstorms"],"parameters":[{"name":"brainstormId","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/brainstorms/{brainstormId}/publish":{"post":{"operationId":"brainstorms.publish","summary":"Publish a brainstorm","description":"Makes the board readable by anyone with its link, with no account and nothing to accept. The public view shows the boxes, their tree position and their tags — never assignees, comments, files or notes. Returns the brainstorm, including its publicUrl.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrainstormSummary"}}}},"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"},"delete":{"operationId":"brainstorms.unpublish","summary":"Un-publish a brainstorm","description":"Takes the board off the internet. Immediate: the link stops working for everyone who already has it, including anyone with the page open.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrainstormSummary"}}}},"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/brainstorms/{brainstormId}/ideas":{"get":{"operationId":"ideas.list","summary":"List a brainstorm's ideas","description":"Every idea on the board, depth-first from its root ideas — the order the canvas reads as a tree.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","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/Idea"}}},"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":"ideas.create","summary":"Add an idea","description":"Adds one box to the board. Set `parentId` to nest it under an existing idea — omit it for a root idea.","tags":["brainstorms"],"parameters":[{"name":"brainstormId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"parentId":{"type":"string","description":"An existing idea's id, to nest under it."}},"required":["title"]}}}},"responses":{"201":{"description":"CREATED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Idea"}}}},"400":{"description":"VALIDATION_FAILED · INVALID_BOX_TREE","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/ideas/{ideaId}":{"get":{"operationId":"ideas.get","summary":"Get an idea","tags":["brainstorms"],"parameters":[{"name":"ideaId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Idea"}}}},"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":"ideas.update","summary":"Update an idea","description":"Title, notes, tags, assignee, or its parent — moving `parentId` re-parents the box. Refused if the move would create a cycle or self-parent.","tags":["brainstorms"],"parameters":[{"name":"ideaId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"notes":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"assigneeId":{"type":"string","description":"Member id, or null to unassign."},"parentId":{"type":"string","description":"A different idea's id to nest under, or null to make it a root idea."}}}}}},"responses":{"200":{"description":"SUCCESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Idea"}}}},"400":{"description":"VALIDATION_FAILED · INVALID_BOX_TREE","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 · 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":["flows:write"]}],"x-minRole":"member"},"delete":{"operationId":"ideas.remove","summary":"Delete an idea","description":"Bridges the gap it leaves: this idea's children are re-parented onto its own parent (or promoted to root ideas, if it had none), so removing a box from the middle of a branch doesn't orphan what nested under it. This cannot be undone.","tags":["brainstorms"],"parameters":[{"name":"ideaId","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/ideas/{ideaId}/comments":{"get":{"operationId":"ideas.comments.list","summary":"List comments","tags":["brainstorms"],"parameters":[{"name":"ideaId","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/IdeaComment"}}},"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":"ideas.comments.create","summary":"Comment on an idea","description":"Discussion is never frozen — commenting works whatever state the board or the idea is in.","tags":["brainstorms"],"parameters":[{"name":"ideaId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Plain text. Blank lines start a new paragraph."}},"required":["body"]}}}},"responses":{"201":{"description":"CREATED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeaComment"}}}},"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/ideas/{ideaId}/attachments":{"post":{"operationId":"ideas.attachments.create","summary":"Attach a file","description":"A reference file on the idea. `multipart/form-data`.","tags":["brainstorms"],"parameters":[{"name":"ideaId","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"}}}}