{ "components": { "schemas": { "ErrorBody": { "additionalProperties": true, "properties": { "category": { "enum": [ "validation", "authentication", "authorization", "not_found", "conflict", "policy", "rate_limited", "upstream", "unavailable", "internal" ], "type": "string" }, "code": { "pattern": "^[A-Z][A-Z0-9_]*$", "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "error": { "type": "string" }, "reasonCodes": { "items": { "type": "string" }, "type": "array" }, "recovery": { "items": { "additionalProperties": true, "properties": { "action": { "type": "string" }, "description": { "type": "string" }, "href": { "type": "string" } }, "required": [ "action", "description" ], "type": "object" }, "type": "array" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" }, "retryable": { "type": "boolean" } }, "required": [ "error", "code", "category", "retryable", "requestId" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "description": "A workspace token (bnd_...) in Authorization: Bearer. Issued once; stored only as a hash.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "The Bind HTTP API. Generated from the route registry (src/api/registry.ts; docs/decisions/0034). Do not edit this file by hand: run npm run api:spec.", "title": "Bind API", "version": "0.1.0" }, "openapi": "3.0.3", "paths": { "/api/account/invites/accept": { "post": { "description": "Access: an account. Send a Privy access token (from signing in with Google or a wallet) as Authorization: Bearer. A workspace token is refused with 401. The route answers 503 when sign-in is not configured.", "operationId": "acceptInvite", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "code": { "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "type": "object" } } }, "description": "The workspace joined." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The invitation cannot be used (unknown, used, revoked or expired: one answer)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The account already belongs to the workspace (ALREADY_MEMBER)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sign-in is not configured on this server (no Privy app), or the account store is unavailable." } }, "security": [ { "bearerAuth": [] } ], "summary": "Join a workspace as staff with a single-use invitation code.", "tags": [ "People" ], "x-bind-access": "account" } }, "/api/account/workspaces": { "get": { "description": "Access: an account. Send a Privy access token (from signing in with Google or a wallet) as Authorization: Bearer. A workspace token is refused with 401. The route answers 503 when sign-in is not configured.", "operationId": "listAccountWorkspaces", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "id", "name", "role" ], "type": "object" }, "type": "array" } } }, "description": "Workspaces." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sign-in is not configured on this server (no Privy app), or the account store is unavailable." } }, "security": [ { "bearerAuth": [] } ], "summary": "The workspaces the signed-in account belongs to, with its role in each.", "tags": [ "People" ], "x-bind-access": "account" }, "post": { "description": "Access: an account. Send a Privy access token (from signing in with Google or a wallet) as Authorization: Bearer. A workspace token is refused with 401. The route answers 503 when sign-in is not configured.", "operationId": "createAccountWorkspace", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "id": { "minLength": 1, "type": "string" }, "name": { "minLength": 1, "type": "string" }, "templateId": { "minLength": 1, "type": "string" } }, "required": [ "id", "name", "templateId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "enum": [ "owner" ], "type": "string" } }, "required": [ "id", "name", "role" ], "type": "object" } } }, "description": "The new workspace." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The workspace id is not available." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sign-in is not configured on this server (no Privy app), or the account store is unavailable." } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a workspace from a template and become its owner.", "tags": [ "People" ], "x-bind-access": "account" } }, "/api/approvals/{id}/approve": { "post": { "description": "Access: a workspace token of an owner. The service checks that the approval or order belongs to the caller's workspace; another workspace's id is answered as not found.", "operationId": "approveApproval", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "effectId": { "type": "string" }, "inDoubt": { "enum": [ true ], "type": "boolean" }, "orderId": { "type": "string" }, "state": { "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "workflowId", "state" ], "type": "object" } } }, "description": "The workflow after the approval, with its order." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The approval is not found in your workspace (APPROVAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The approval cannot be decided now, for example it is expired or already decided." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Approve a pending approval. The order is submitted once, as the owner token's label.", "tags": [ "Approvals" ], "x-bind-access": "owner-any" } }, "/api/approvals/{id}/reject": { "post": { "description": "Access: a workspace token of an owner. The service checks that the approval or order belongs to the caller's workspace; another workspace's id is answered as not found.", "operationId": "rejectApproval", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "reason": { "maxLength": 500, "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "approvalId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "rejected", "revoked" ], "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "status", "approvalId", "workflowId", "state" ], "type": "object" } } }, "description": "The decision." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The approval is not found in your workspace (APPROVAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The approval cannot be decided now." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Reject a pending approval. The workflow is cancelled and nothing is ordered.", "tags": [ "Approvals" ], "x-bind-access": "owner-any" } }, "/api/approvals/{id}/revoke": { "post": { "description": "Access: a workspace token of an owner. The service checks that the approval or order belongs to the caller's workspace; another workspace's id is answered as not found.", "operationId": "revokeApproval", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "reason": { "maxLength": 500, "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "approvalId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "rejected", "revoked" ], "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "status", "approvalId", "workflowId", "state" ], "type": "object" } } }, "description": "The decision." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The approval is not found in your workspace (APPROVAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The approval cannot be decided now." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Revoke an approval that was given. Recorded as revoked, not rejected.", "tags": [ "Approvals" ], "x-bind-access": "owner-any" } }, "/api/auth/session": { "post": { "description": "Access: an account. Send a Privy access token (from signing in with Google or a wallet) as Authorization: Bearer. A workspace token is refused with 401. The route answers 503 when sign-in is not configured.", "operationId": "createSession", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "displayName": { "maxLength": 80, "minLength": 1, "type": "string" }, "workspaceId": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "workspaceId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" }, "sessionToken": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "sessionToken", "expiresAt", "workspaceId", "role" ], "type": "object" } } }, "description": "The session token. Send it as a bearer token like a workspace token." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found or the account is not a member (the same answer for both)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Sign-in is not configured on this server (no Privy app), or the account store is unavailable." } }, "security": [ { "bearerAuth": [] } ], "summary": "Sign in: swap a Privy access token for a short-lived session in one workspace the account belongs to.", "tags": [ "People" ], "x-bind-access": "account" } }, "/api/auth/sign-out": { "post": { "description": "Access: any valid workspace token. The answer is scoped to the caller's own workspace.", "operationId": "signOut", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "signedOut": { "type": "boolean" } }, "required": [ "signedOut" ], "type": "object" } } }, "description": "signedOut is true when an account session was ended, and false for a workspace token, which is not a session and keeps working." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "End the account session this request used.", "tags": [ "People" ], "x-bind-access": "authenticated" } }, "/api/demo": { "post": { "description": "Access: public. No token is needed.", "operationId": "createDemo", "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "token": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "workspaceId", "token", "expiresAt" ], "type": "object" } } }, "description": "Created. The owner token is in the body and is shown only here. Never cached." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Demo workspaces are off on this server (code DEMO_DISABLED). They are off in production unless BIND_DEMO_ENABLED=true." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The limit on active demos is reached (code DEMO_CAPACITY_REACHED), or another create holds the lock (code DEMO_BUSY, Retry-After: 3)." } }, "security": [], "summary": "Create a throwaway demo workspace: four hours, simulated only, with one real pending approval. Returns its owner token once.", "tags": [ "Demo" ], "x-bind-access": "public" } }, "/api/me": { "get": { "description": "Access: any valid workspace token. The answer is scoped to the caller's own workspace.", "operationId": "getMe", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "agentsPaused": { "type": "boolean" }, "credential": { "enum": [ "workspace_token", "account_session" ], "type": "string" }, "label": { "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" }, "workspaceId": { "type": "string" }, "workspaceName": { "type": "string" } }, "required": [ "workspaceId", "workspaceName", "role", "label", "credential", "agentsPaused" ], "type": "object" } } }, "description": "The caller's identity in its workspace. Sent with Cache-Control: no-store." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The caller's workspace no longer exists. The same body a missing workspace gets elsewhere." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Who the bearer token is: its workspace, role, label, credential kind and the pause switch. Never a secret.", "tags": [ "Workspaces" ], "x-bind-access": "authenticated" } }, "/api/openapi.json": { "get": { "description": "Access: public. No token is needed.", "operationId": "getOpenApi", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "components": { "additionalProperties": true, "properties": { "securitySchemes": { "additionalProperties": {}, "type": "object" } }, "required": [ "securitySchemes" ], "type": "object" }, "info": { "additionalProperties": true, "properties": { "title": { "enum": [ "Bind API" ], "type": "string" }, "version": { "type": "string" } }, "required": [ "title", "version" ], "type": "object" }, "openapi": { "enum": [ "3.0.3" ], "type": "string" }, "paths": { "additionalProperties": { "additionalProperties": {}, "type": "object" }, "type": "object" } }, "required": [ "openapi", "info", "paths", "components" ], "type": "object" } } }, "description": "OpenAPI 3.0.3 document." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." } }, "security": [], "summary": "The OpenAPI 3.0 document of this API, built from the route registry (ADR 0034).", "tags": [ "Monitoring" ], "x-bind-access": "public" } }, "/api/orders/{id}/confirm-settlement": { "post": { "description": "Access: a workspace token of an owner. The service checks that the approval or order belongs to the caller's workspace; another workspace's id is answered as not found.", "operationId": "confirmOrderSettlement", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "alreadyReconciled": { "type": "boolean" }, "discrepancyReason": { "type": "string" }, "hold": { "type": "string" }, "pending": { "enum": [ "AWAITING_DELIVERY_RECEIPT", "AWAITING_SUPPLIER_BILL", "AWAITING_SETTLEMENT_CONFIRMATION" ], "type": "string" }, "reconciled": { "type": "boolean" }, "status": { "type": "string" }, "txHash": { "type": "string" }, "varianceCents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "status", "reconciled" ], "type": "object" } } }, "description": "The settlement outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The order is not found in your workspace (ORDER_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The order is not waiting for settlement confirmation." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Finish a payment that was sent but not yet confirmed. It pays nothing.", "tags": [ "Orders" ], "x-bind-access": "owner-any" } }, "/api/orders/{id}/reconcile": { "post": { "description": "Access: a workspace token of an owner. The service checks that the approval or order belongs to the caller's workspace; another workspace's id is answered as not found.", "operationId": "reconcileOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "alreadyReconciled": { "type": "boolean" }, "discrepancyReason": { "type": "string" }, "hold": { "type": "string" }, "pending": { "enum": [ "AWAITING_DELIVERY_RECEIPT", "AWAITING_SUPPLIER_BILL", "AWAITING_SETTLEMENT_CONFIRMATION" ], "type": "string" }, "reconciled": { "type": "boolean" }, "status": { "type": "string" }, "txHash": { "type": "string" }, "varianceCents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "status", "reconciled" ], "type": "object" } } }, "description": "The match and, when paid, the transaction." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The order is not found in your workspace (ORDER_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The order is not in a state that can be reconciled." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Match the delivery receipt and the bill to the order, and settle it if they match.", "tags": [ "Orders" ], "x-bind-access": "owner-any" } }, "/api/public-config": { "get": { "description": "Access: public. No token is needed.", "operationId": "getPublicConfig", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "privyAppId": { "maxLength": 128, "minLength": 1, "nullable": true, "type": "string" } }, "required": [ "privyAppId" ], "type": "object" } } }, "description": "Public configuration. Never cached." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." } }, "security": [], "summary": "The public browser configuration: the Privy app id for sign-in, or null. Nothing secret (ADR 0070).", "tags": [ "Monitoring" ], "x-bind-access": "public" } }, "/api/templates": { "get": { "description": "Access: public. No token is needed.", "operationId": "listTemplates", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "dataSources": { "items": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "readOnly": { "enum": [ true ], "type": "boolean" } }, "required": [ "id", "label", "kind", "readOnly" ], "type": "object" }, "type": "array" }, "defaultApprovalThresholdCents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "defaultDailyLimitCents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": { "type": "string" }, "modules": { "additionalProperties": true, "properties": { "stock": { "type": "boolean" }, "suppliers": { "type": "boolean" } }, "required": [ "stock", "suppliers" ], "type": "object" }, "name": { "type": "string" }, "outputs": { "items": { "additionalProperties": true, "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "report", "notice", "order" ], "type": "string" } }, "required": [ "id", "kind", "description" ], "type": "object" }, "type": "array" }, "roles": { "items": { "additionalProperties": true, "properties": { "roleName": { "type": "string" } }, "required": [ "roleName" ], "type": "object" }, "type": "array" }, "templateId": { "type": "string" }, "triggers": { "items": { "additionalProperties": true, "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "schedule", "event", "manual" ], "type": "string" } }, "required": [ "id", "kind", "description" ], "type": "object" }, "type": "array" } }, "required": [ "templateId", "name", "description", "defaultDailyLimitCents", "defaultApprovalThresholdCents", "roles" ], "type": "object" }, "type": "array" } } }, "description": "Template catalogue." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." } }, "security": [], "summary": "The reference templates a workspace can start from.", "tags": [ "Templates" ], "x-bind-access": "public" } }, "/api/templates/{id}/blueprint": { "get": { "description": "Access: public. No token is needed.", "operationId": "getTemplateBlueprint", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "defaultApprovalThresholdCents": { "type": "number" }, "defaultDailyLimitCents": { "type": "number" }, "description": { "type": "string" }, "name": { "type": "string" }, "referenceTemplateId": { "type": "string" }, "suggestedRoles": { "items": { "additionalProperties": true, "properties": { "roleName": { "type": "string" } }, "required": [ "roleName" ], "type": "object" }, "type": "array" }, "suggestedSuppliers": { "items": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "suggestedSupplies": { "items": { "additionalProperties": true, "properties": { "name": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "sku", "name" ], "type": "object" }, "type": "array" } }, "required": [ "referenceTemplateId", "name", "description", "defaultDailyLimitCents", "defaultApprovalThresholdCents", "suggestedRoles", "suggestedSuppliers", "suggestedSupplies" ], "type": "object" } } }, "description": "Blueprint." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No template has that id." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." } }, "security": [], "summary": "The pre-fill for onboarding from one reference template. Creates nothing.", "tags": [ "Templates" ], "x-bind-access": "public" } }, "/api/webhooks/incoming": { "post": { "description": "Access: not a bearer route. The body is authenticated by an HMAC-SHA256 over `timestamp + \".\" + raw body`, hex, in the x-bind-signature header, with the timestamp in x-bind-timestamp. A surface event uses the workspace's surface secret; a standard event uses the configured webhook secret. An unsigned or wrongly signed request is refused with 401 and processes nothing.", "operationId": "receiveWebhook", "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "additionalProperties": true, "properties": { "actorId": { "maxLength": 120, "minLength": 2, "type": "string" }, "actorRole": { "enum": [ "owner", "staff" ], "type": "string" }, "eventId": { "maxLength": 120, "minLength": 4, "type": "string" }, "eventType": { "enum": [ "SURFACE_STOCK_OBSERVED" ], "type": "string" }, "note": { "maxLength": 500, "type": "string" }, "observedQuantity": { "maximum": 1000000, "minimum": 0, "type": "integer" }, "sku": { "maxLength": 120, "minLength": 1, "type": "string" }, "surface": { "enum": [ "whatsapp", "telegram", "instagram", "slack", "email", "email_magic_link", "pos_webhook", "web_ui" ], "type": "string" }, "workspaceId": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "eventType", "eventId", "workspaceId", "surface", "actorId", "actorRole", "sku", "observedQuantity" ], "type": "object" }, { "additionalProperties": true, "properties": { "actorId": { "maxLength": 120, "minLength": 2, "type": "string" }, "actorRole": { "enum": [ "owner", "staff" ], "type": "string" }, "approvalId": { "maxLength": 120, "minLength": 2, "type": "string" }, "decision": { "enum": [ "approve", "reject" ], "type": "string" }, "eventId": { "maxLength": 120, "minLength": 4, "type": "string" }, "eventType": { "enum": [ "SURFACE_OWNER_APPROVAL_DECISION" ], "type": "string" }, "reason": { "maxLength": 500, "type": "string" }, "surface": { "enum": [ "whatsapp", "telegram", "instagram", "slack", "email", "email_magic_link", "pos_webhook", "web_ui" ], "type": "string" }, "workspaceId": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "eventType", "eventId", "workspaceId", "surface", "actorId", "actorRole", "approvalId", "decision" ], "type": "object" }, { "additionalProperties": true, "properties": { "actorId": { "maxLength": 120, "minLength": 2, "type": "string" }, "actorRole": { "enum": [ "owner", "staff" ], "type": "string" }, "eventId": { "maxLength": 120, "minLength": 4, "type": "string" }, "eventType": { "enum": [ "SURFACE_AGENT_PAUSE_TOGGLE" ], "type": "string" }, "paused": { "type": "boolean" }, "surface": { "enum": [ "whatsapp", "telegram", "instagram", "slack", "email", "email_magic_link", "pos_webhook", "web_ui" ], "type": "string" }, "workspaceId": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "eventType", "eventId", "workspaceId", "surface", "actorId", "actorRole", "paused" ], "type": "object" } ] }, { "additionalProperties": true, "properties": { "eventId": { "maxLength": 200, "minLength": 1, "type": "string" }, "payload": { "additionalProperties": {}, "type": "object" }, "provider": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "provider", "eventId" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "additionalProperties": true, "properties": { "bindingStatus": { "type": "string" }, "effectiveRole": { "enum": [ "owner", "staff" ], "type": "string" }, "eventType": { "enum": [ "SURFACE_STOCK_OBSERVED" ], "type": "string" }, "observedQuantity": { "type": "number" }, "parLevel": { "type": "number" }, "replenishmentResult": { "additionalProperties": true, "nullable": true, "properties": { "approvalId": { "type": "string" }, "orderId": { "type": "string" }, "state": { "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "workflowId", "state" ], "type": "object" }, "replenishmentSkipped": { "enum": [ "AGENTS_PAUSED" ], "type": "string" }, "replenishmentTriggered": { "type": "boolean" }, "status": { "enum": [ "processed" ], "type": "string" } }, "required": [ "status", "effectiveRole", "bindingStatus", "eventType", "observedQuantity", "replenishmentTriggered", "replenishmentResult" ], "type": "object" }, { "additionalProperties": true, "properties": { "approvalId": { "type": "string" }, "bindingStatus": { "type": "string" }, "decision": { "enum": [ "approve", "reject" ], "type": "string" }, "effectiveRole": { "enum": [ "owner", "staff" ], "type": "string" }, "eventType": { "enum": [ "SURFACE_OWNER_APPROVAL_DECISION" ], "type": "string" }, "result": { "additionalProperties": true, "properties": { "effectId": { "type": "string" }, "inDoubt": { "enum": [ true ], "type": "boolean" }, "orderId": { "type": "string" }, "state": { "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "workflowId", "state" ], "type": "object" }, "status": { "enum": [ "processed" ], "type": "string" } }, "required": [ "status", "effectiveRole", "bindingStatus", "eventType", "decision" ], "type": "object" }, { "additionalProperties": true, "properties": { "bindingStatus": { "type": "string" }, "effectiveRole": { "enum": [ "owner", "staff" ], "type": "string" }, "eventType": { "enum": [ "SURFACE_AGENT_PAUSE_TOGGLE" ], "type": "string" }, "paused": { "type": "boolean" }, "status": { "enum": [ "processed" ], "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "status", "effectiveRole", "bindingStatus", "eventType", "workspaceId", "paused" ], "type": "object" }, { "additionalProperties": true, "properties": { "eventId": { "type": "string" }, "status": { "enum": [ "duplicate" ], "type": "string" } }, "required": [ "status", "eventId" ], "type": "object" } ] }, { "additionalProperties": true, "properties": { "accepted": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "accepted" ], "type": "object" } ] } } }, "description": "Processed, or a duplicate. Surface and standard answers have different fields." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A standard event without provider and eventId, or a surface event the server cannot process." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The signature or the timestamp is wrong or expired. The same body answers an unknown workspace." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Actor is not authorized for this event: no binding in this workspace, or a staff binding asked for an owner action. The code is SURFACE_ROLE_VIOLATION." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A surface approval decision for an approval that is not in this workspace (APPROVAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A surface approval decision that cannot be made now." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": true, "properties": { "category": { "enum": [ "validation", "authentication", "authorization", "not_found", "conflict", "policy", "rate_limited", "upstream", "unavailable", "internal" ], "type": "string" }, "code": { "pattern": "^[A-Z][A-Z0-9_]*$", "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "error": { "type": "string" }, "reasonCodes": { "items": { "type": "string" }, "type": "array" }, "recovery": { "items": { "additionalProperties": true, "properties": { "action": { "type": "string" }, "description": { "type": "string" }, "href": { "type": "string" } }, "required": [ "action", "description" ], "type": "object" }, "type": "array" }, "requestId": { "type": "string" }, "retryAfterSeconds": { "type": "integer" }, "retryable": { "type": "boolean" } }, "required": [ "error", "code", "category", "retryable", "requestId" ], "type": "object" }, { "additionalProperties": true, "properties": { "accepted": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "accepted" ], "type": "object" } ] } } }, "description": "Webhook signing is not configured, or the event could not be recorded (retry later)." } }, "security": [], "summary": "A surface event (signed with the workspace's surface secret) or a standard event (signed with BIND_WEBHOOK_SECRET). The body is the signed bytes.", "tags": [ "Webhooks" ], "x-bind-access": "signed-webhook" } }, "/api/workspaces": { "get": { "description": "Access: any valid workspace token. The answer is scoped to the caller's own workspace.", "operationId": "listWorkspaces", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "agents_paused": { "type": "boolean" }, "approval_threshold_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "budget_daily_limit_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "created_at": { "format": "date-time", "type": "string" }, "demo_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "is_demo": { "type": "boolean" }, "name": { "type": "string" }, "settlement_address": { "nullable": true, "type": "string" }, "settlement_mode": { "type": "string" }, "template_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "webhook_secret_version": { "type": "integer" } }, "required": [ "id", "name", "template_id", "settlement_address", "settlement_mode", "budget_daily_limit_cents", "approval_threshold_cents", "created_at", "updated_at", "agents_paused", "webhook_secret_version" ], "type": "object" }, "type": "array" } } }, "description": "The caller's workspace, as a one-item list." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The caller's own workspace (never another one).", "tags": [ "Workspaces" ], "x-bind-access": "authenticated" }, "post": { "description": "Access: public. No token is needed.", "operationId": "createWorkspace", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "id": { "minLength": 1, "type": "string" }, "name": { "minLength": 1, "type": "string" }, "templateId": { "minLength": 1, "type": "string" } }, "required": [ "id", "name", "templateId" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "message": { "enum": [ "Workspace provisioned" ], "type": "string" }, "ownerToken": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "token" ], "type": "object" }, "template": { "additionalProperties": true, "properties": { "dataSources": { "items": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" }, "readOnly": { "enum": [ true ], "type": "boolean" } }, "required": [ "id", "label", "kind", "readOnly" ], "type": "object" }, "type": "array" }, "defaultApprovalThresholdCents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "defaultDailyLimitCents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "description": { "type": "string" }, "modules": { "additionalProperties": true, "properties": { "stock": { "type": "boolean" }, "suppliers": { "type": "boolean" } }, "required": [ "stock", "suppliers" ], "type": "object" }, "name": { "type": "string" }, "outputs": { "items": { "additionalProperties": true, "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "report", "notice", "order" ], "type": "string" } }, "required": [ "id", "kind", "description" ], "type": "object" }, "type": "array" }, "roles": { "items": { "additionalProperties": true, "properties": { "roleName": { "type": "string" } }, "required": [ "roleName" ], "type": "object" }, "type": "array" }, "templateId": { "type": "string" }, "triggers": { "items": { "additionalProperties": true, "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "schedule", "event", "manual" ], "type": "string" } }, "required": [ "id", "kind", "description" ], "type": "object" }, "type": "array" } }, "required": [ "templateId", "name", "description", "defaultDailyLimitCents", "defaultApprovalThresholdCents", "roles" ], "type": "object" } }, "required": [ "message", "template", "ownerToken" ], "type": "object" } } }, "description": "Created. The owner token is in the body and is shown only here." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The workspace id is taken. Nothing is changed." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." } }, "security": [], "summary": "Create a workspace from a reference template. Returns its first owner token once.", "tags": [ "Workspaces" ], "x-bind-access": "public" } }, "/api/workspaces/onboard": { "post": { "description": "Access: public. No token is needed.", "operationId": "onboardWorkspace", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "approvalThresholdCents": { "minimum": 0, "type": "integer" }, "budgetDailyLimitCents": { "exclusiveMinimum": true, "minimum": 0, "type": "integer" }, "businessType": { "default": "kitchen", "enum": [ "kitchen", "cafe", "roastery", "retail", "service", "custom" ], "type": "string" }, "name": { "maxLength": 120, "minLength": 2, "type": "string" }, "referenceTemplateId": { "type": "string" }, "settlementAddress": { "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string" }, "settlementMode": { "default": "local", "enum": [ "local", "arc-testnet" ], "type": "string" }, "suppliers": { "default": [], "items": { "additionalProperties": true, "properties": { "adapterType": { "default": "manual_quote", "enum": [ "simulated_sysco", "simulated_baldor", "rest_api", "manual_quote" ], "type": "string" }, "contactEmail": { "anyOf": [ { "format": "email", "type": "string" }, { "enum": [ "" ], "type": "string" } ] }, "endpointUrl": { "type": "string" }, "id": { "maxLength": 64, "minLength": 2, "type": "string" }, "isSimulated": { "default": true, "type": "boolean" }, "name": { "maxLength": 120, "minLength": 2, "type": "string" }, "verified": { "default": true, "type": "boolean" } }, "required": [ "id", "name" ], "type": "object" }, "type": "array" }, "supplies": { "default": [], "items": { "additionalProperties": true, "properties": { "category": { "default": "General", "maxLength": 64, "minLength": 2, "type": "string" }, "currentQuantity": { "minimum": 0, "type": "number" }, "name": { "maxLength": 120, "minLength": 2, "type": "string" }, "parLevel": { "minimum": 0, "type": "number" }, "preferredSupplierId": { "type": "string" }, "reorderQuantity": { "exclusiveMinimum": true, "minimum": 0, "type": "number" }, "sku": { "maxLength": 64, "minLength": 2, "type": "string" }, "unit": { "default": "unit", "maxLength": 32, "minLength": 1, "type": "string" }, "unitPriceCents": { "minimum": 0, "type": "integer" } }, "required": [ "sku", "name", "currentQuantity", "parLevel", "reorderQuantity", "unitPriceCents" ], "type": "object" }, "type": "array" }, "workspaceId": { "maxLength": 64, "minLength": 3, "pattern": "^[a-z0-9-_]+$", "type": "string" } }, "required": [ "workspaceId", "name", "budgetDailyLimitCents", "approvalThresholdCents" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "derivedFiles": { "additionalProperties": true, "properties": { "agentsSpecPath": { "type": "string" }, "skillSpecPath": { "type": "string" } }, "required": [ "agentsSpecPath", "skillSpecPath" ], "type": "object" }, "name": { "type": "string" }, "ownerToken": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "token" ], "type": "object" }, "provenance": { "enum": [ "OWNER_CONFIRMED" ], "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "workspaceId", "name", "provenance", "derivedFiles", "ownerToken" ], "type": "object" } } }, "description": "Created. The owner token is in the body and is shown only here." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The workspace id is taken. Nothing is changed." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." } }, "security": [], "summary": "Create a blank or owner-configured workspace. Returns its first owner token once.", "tags": [ "Workspaces" ], "x-bind-access": "public" } }, "/api/workspaces/{id}": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getWorkspace", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "forbiddenCapabilities": { "items": { "type": "string" }, "type": "array" }, "roles": { "items": { "additionalProperties": true, "properties": { "allowed_tools": { "items": { "type": "string" }, "type": "array" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "nullable": true, "type": "string" }, "display_name": { "type": "string" }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "permitted_effects": { "items": { "type": "string" }, "type": "array" }, "role_name": { "type": "string" }, "spending_limit_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "role_name", "display_name", "description", "permitted_effects", "spending_limit_cents", "enabled", "created_at", "allowed_tools" ], "type": "object" }, "type": "array" }, "safeAgentTools": { "items": { "type": "string" }, "type": "array" }, "treasuryBalanceCents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "workspace": { "additionalProperties": true, "properties": { "agents_paused": { "type": "boolean" }, "approval_threshold_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "budget_daily_limit_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "created_at": { "format": "date-time", "type": "string" }, "demo_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "is_demo": { "type": "boolean" }, "name": { "type": "string" }, "settlement_address": { "nullable": true, "type": "string" }, "settlement_mode": { "type": "string" }, "template_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "webhook_secret_version": { "type": "integer" } }, "required": [ "id", "name", "template_id", "settlement_address", "settlement_mode", "budget_daily_limit_cents", "approval_threshold_cents", "created_at", "updated_at", "agents_paused", "webhook_secret_version" ], "type": "object" } }, "required": [ "workspace", "roles", "treasuryBalanceCents", "safeAgentTools", "forbiddenCapabilities" ], "type": "object" } } }, "description": "Workspace detail." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "A workspace with its agent roles, treasury balance and the tool registry.", "tags": [ "Workspaces" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/accounting/ledger": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getLedger", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "format", "required": false, "schema": { "enum": [ "json", "csv" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "amount_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "created_at": { "format": "date-time", "type": "string" }, "credit_account": { "type": "string" }, "currency": { "type": "string" }, "debit_account": { "type": "string" }, "entry_number": { "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "memo": { "type": "string" }, "order_id": { "nullable": true, "type": "string" }, "provenance": { "type": "string" }, "tx_hash": { "nullable": true, "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "order_id", "entry_number", "debit_account", "credit_account", "amount_cents", "currency", "memo", "provenance", "tx_hash", "idempotency_key", "created_at" ], "type": "object" }, "type": "array" } } }, "description": "Journal entries (JSON). With format=csv: a text/csv attachment of the same rows." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Journal entries for paid and reconciled orders. ?format=csv returns the same rows as text/csv.", "tags": [ "Accounting" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/agents": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getAgents", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "forbiddenCapabilities": { "items": { "type": "string" }, "type": "array" }, "roles": { "items": { "additionalProperties": true, "properties": { "allowed_tools": { "items": { "type": "string" }, "type": "array" }, "created_at": { "format": "date-time", "type": "string" }, "description": { "nullable": true, "type": "string" }, "display_name": { "type": "string" }, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "permitted_effects": { "items": { "type": "string" }, "type": "array" }, "role_name": { "type": "string" }, "spending_limit_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "role_name", "display_name", "description", "permitted_effects", "spending_limit_cents", "enabled", "created_at", "allowed_tools" ], "type": "object" }, "type": "array" }, "safeAgentTools": { "items": { "type": "string" }, "type": "array" } }, "required": [ "roles", "safeAgentTools", "forbiddenCapabilities" ], "type": "object" } } }, "description": "Roles and the tool lists." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Agent roles, with the tool registry and the forbidden capabilities.", "tags": [ "Agents" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "upsertAgentRole", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "allowedTools": { "items": { "type": "string" }, "minItems": 1, "type": "array" }, "description": { "maxLength": 1000, "minLength": 5, "type": "string" }, "displayName": { "maxLength": 120, "minLength": 2, "type": "string" }, "enabled": { "default": true, "type": "boolean" }, "permittedEffects": { "items": { "enum": [ "read", "external_request", "commercial_commitment" ], "type": "string" }, "minItems": 1, "type": "array" }, "roleName": { "maxLength": 64, "minLength": 2, "pattern": "^[a-z0-9_]+$", "type": "string" }, "spendingLimitCents": { "minimum": 0, "type": "integer" } }, "required": [ "roleName", "displayName", "description", "permittedEffects", "spendingLimitCents", "allowedTools" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "allowedTools": { "items": { "type": "string" }, "type": "array" }, "derivedFiles": { "additionalProperties": true, "properties": { "agentsSpecPath": { "type": "string" }, "skillSpecPath": { "type": "string" } }, "required": [ "agentsSpecPath", "skillSpecPath" ], "type": "object" }, "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "permittedEffects": { "items": { "type": "string" }, "type": "array" }, "roleId": { "type": "string" }, "roleName": { "type": "string" }, "spendingLimitCents": { "type": "number" }, "workspaceId": { "type": "string" } }, "required": [ "roleId", "workspaceId", "roleName", "displayName", "permittedEffects", "spendingLimitCents", "allowedTools", "enabled", "derivedFiles" ], "type": "object" } } }, "description": "The stored role and where its generated spec was written." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid role, or a forbidden or unknown tool (FORBIDDEN_CAPABILITY for a forbidden one)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Add or update an agent role. Only the typed tool registry is allowed; forbidden capabilities are refused.", "tags": [ "Agents" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/agents-paused": { "put": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "setAgentsPaused", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "paused": { "type": "boolean" } }, "required": [ "paused" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "paused": { "type": "boolean" }, "workspaceId": { "type": "string" } }, "required": [ "workspaceId", "paused" ], "type": "object" } } }, "description": "The stored value, read back from the workspace." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "paused must be true or false." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The change could not be recorded." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The pause switch. While paused, no commitment is made and no replenishment starts (ADR 0022).", "tags": [ "Controls" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/analytics/accounts": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listAnalyticsAccounts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "brandLabel": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "isSimulated": { "type": "boolean" }, "lastSyncedAt": { "format": "date-time", "nullable": true, "type": "string" }, "postCount": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "timeZone": { "type": "string" } }, "required": [ "id", "provider", "brandLabel", "timeZone", "isSimulated", "status", "createdAt", "lastSyncedAt", "postCount" ], "type": "object" }, "type": "array" } } }, "description": "The accounts, oldest first." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The analytics accounts of this workspace, with when each was last synced and how many posts it holds. A workspace whose template has no analytics module has none: the list is empty.", "tags": [ "Analytics" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "createAnalyticsAccount", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "brandLabel": { "maxLength": 80, "minLength": 1, "type": "string" }, "provider": { "maxLength": 40, "minLength": 1, "type": "string" }, "timeZone": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "provider", "brandLabel" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "brandLabel": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "isSimulated": { "type": "boolean" }, "lastSyncedAt": { "format": "date-time", "nullable": true, "type": "string" }, "postCount": { "type": "integer" }, "provider": { "type": "string" }, "status": { "type": "string" }, "timeZone": { "type": "string" } }, "required": [ "id", "provider", "brandLabel", "timeZone", "isSimulated", "status", "createdAt", "lastSyncedAt", "postCount" ], "type": "object" } } }, "description": "The account, now connected." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed input (INVALID_INPUT: a brand label of 1 to 80 characters, or an IANA time zone). Also: TEMPLATE_HAS_NO_ANALYTICS, or ANALYTICS_PROVIDER_NOT_AVAILABLE for any provider other than simulated." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A demo workspace does not change analytics (ANALYTICS_DEMO_REFUSED)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The workspace already has the most accounts it can have (ANALYTICS_ACCOUNT_LIMIT)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Connect an analytics account. Only the simulated provider is available: its data is labelled simulated everywhere.", "tags": [ "Analytics" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/analytics/accounts/{accountId}/sync": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "syncAnalyticsAccount", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "accountId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "accountId": { "type": "string" }, "inserted": { "type": "integer" }, "posts": { "type": "integer" }, "simulated": { "type": "boolean" }, "syncedAt": { "format": "date-time", "type": "string" }, "updated": { "type": "integer" } }, "required": [ "accountId", "posts", "inserted", "updated", "syncedAt", "simulated" ], "type": "object" } } }, "description": "What the sync stored: how many posts, how many were new and how many were updated." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This workspace's template has no post analytics module (TEMPLATE_HAS_NO_ANALYTICS), or the stored provider is not available." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A demo workspace does not change analytics (ANALYTICS_DEMO_REFUSED)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No such analytics account in this workspace (ANALYTICS_ACCOUNT_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The account is disabled (ANALYTICS_ACCOUNT_DISABLED)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This account was attempted within the minimum interval (ANALYTICS_SYNC_TOO_SOON). Retry-After is set." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The provider did not answer (ANALYTICS_PROVIDER_UNAVAILABLE), or its answer is not valid (ANALYTICS_PROVIDER_OUTPUT_INVALID). Nothing was stored." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Fetch the account's recent posts from its provider and store them. Repeating it leaves the stored posts as they were.", "tags": [ "Analytics" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/analytics/reports": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listAnalyticsReports", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "accountId": { "nullable": true, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "findings": { "additionalProperties": true, "properties": { "countries": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "posts", "top" ], "type": "object" }, "followers": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "status", "posts" ], "type": "object" }, "formats": { "additionalProperties": true, "properties": { "comparisons": { "items": {}, "type": "array" }, "groups": { "items": {}, "type": "array" }, "status": { "type": "string" } }, "required": [ "status", "groups", "comparisons" ], "type": "object" }, "hours": { "additionalProperties": true, "properties": { "eligibleHours": { "items": {}, "type": "array" }, "status": { "type": "string" }, "timeZone": { "type": "string" } }, "required": [ "status", "timeZone", "eligibleHours" ], "type": "object" }, "minimumGroupPosts": { "type": "integer" }, "postCount": { "type": "integer" }, "rankings": { "additionalProperties": true, "properties": { "bottom": { "items": {}, "type": "array" }, "eligible": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "eligible", "top", "bottom" ], "type": "object" }, "simulated": { "type": "boolean" }, "timeZone": { "type": "string" } }, "required": [ "simulated", "timeZone", "postCount", "minimumGroupPosts", "formats", "hours", "followers", "countries", "rankings" ], "type": "object" }, "id": { "type": "string" }, "kind": { "enum": [ "weekly", "on_demand" ], "type": "string" }, "periodEnd": { "type": "string" }, "periodStart": { "type": "string" }, "simulated": { "type": "boolean" }, "text": { "type": "string" } }, "required": [ "id", "accountId", "kind", "periodStart", "periodEnd", "createdAt", "simulated", "text", "findings" ], "type": "object" }, "type": "array" } } }, "description": "The reports, newest first." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The 50 newest analytics reports of this workspace, with their text and findings. Empty for a workspace with no analytics module.", "tags": [ "Analytics" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "createAnalyticsReport", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "accountId": { "maxLength": 64, "minLength": 1, "type": "string" }, "kind": { "enum": [ "on_demand" ], "type": "string" }, "periodEnd": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" }, "periodStart": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } }, "required": [ "kind" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "accountId": { "nullable": true, "type": "string" }, "created": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "findings": { "additionalProperties": true, "properties": { "countries": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "posts", "top" ], "type": "object" }, "followers": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "status", "posts" ], "type": "object" }, "formats": { "additionalProperties": true, "properties": { "comparisons": { "items": {}, "type": "array" }, "groups": { "items": {}, "type": "array" }, "status": { "type": "string" } }, "required": [ "status", "groups", "comparisons" ], "type": "object" }, "hours": { "additionalProperties": true, "properties": { "eligibleHours": { "items": {}, "type": "array" }, "status": { "type": "string" }, "timeZone": { "type": "string" } }, "required": [ "status", "timeZone", "eligibleHours" ], "type": "object" }, "minimumGroupPosts": { "type": "integer" }, "postCount": { "type": "integer" }, "rankings": { "additionalProperties": true, "properties": { "bottom": { "items": {}, "type": "array" }, "eligible": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "eligible", "top", "bottom" ], "type": "object" }, "simulated": { "type": "boolean" }, "timeZone": { "type": "string" } }, "required": [ "simulated", "timeZone", "postCount", "minimumGroupPosts", "formats", "hours", "followers", "countries", "rankings" ], "type": "object" }, "id": { "type": "string" }, "kind": { "enum": [ "weekly", "on_demand" ], "type": "string" }, "periodEnd": { "type": "string" }, "periodStart": { "type": "string" }, "simulated": { "type": "boolean" }, "text": { "type": "string" } }, "required": [ "id", "accountId", "kind", "periodStart", "periodEnd", "createdAt", "simulated", "text", "findings", "created" ], "type": "object" } } }, "description": "The period already had its report, which is returned (created: false)." }, "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "accountId": { "nullable": true, "type": "string" }, "created": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "findings": { "additionalProperties": true, "properties": { "countries": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "posts", "top" ], "type": "object" }, "followers": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "status", "posts" ], "type": "object" }, "formats": { "additionalProperties": true, "properties": { "comparisons": { "items": {}, "type": "array" }, "groups": { "items": {}, "type": "array" }, "status": { "type": "string" } }, "required": [ "status", "groups", "comparisons" ], "type": "object" }, "hours": { "additionalProperties": true, "properties": { "eligibleHours": { "items": {}, "type": "array" }, "status": { "type": "string" }, "timeZone": { "type": "string" } }, "required": [ "status", "timeZone", "eligibleHours" ], "type": "object" }, "minimumGroupPosts": { "type": "integer" }, "postCount": { "type": "integer" }, "rankings": { "additionalProperties": true, "properties": { "bottom": { "items": {}, "type": "array" }, "eligible": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "eligible", "top", "bottom" ], "type": "object" }, "simulated": { "type": "boolean" }, "timeZone": { "type": "string" } }, "required": [ "simulated", "timeZone", "postCount", "minimumGroupPosts", "formats", "hours", "followers", "countries", "rankings" ], "type": "object" }, "id": { "type": "string" }, "kind": { "enum": [ "weekly", "on_demand" ], "type": "string" }, "periodEnd": { "type": "string" }, "periodStart": { "type": "string" }, "simulated": { "type": "boolean" }, "text": { "type": "string" } }, "required": [ "id", "accountId", "kind", "periodStart", "periodEnd", "createdAt", "simulated", "text", "findings", "created" ], "type": "object" } } }, "description": "The report was written now (created: true)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed input (INVALID_INPUT: a period that is not whole days, longer than 92 days, or ends after today). Also TEMPLATE_HAS_NO_ANALYTICS." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A demo workspace does not change analytics (ANALYTICS_DEMO_REFUSED)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No such analytics account in this workspace (ANALYTICS_ACCOUNT_NOT_FOUND), when an accountId is given." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The period has no stored posts yet (ANALYTICS_NO_DATA_YET). Sync the account, then ask again. Nothing is stored for the period." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Write a report for a period (UTC days, at most 92, ending by today). Once per period: asking again for the same period returns the same report.", "tags": [ "Analytics" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/analytics/reports/{reportId}": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getAnalyticsReport", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "reportId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "accountId": { "nullable": true, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "findings": { "additionalProperties": true, "properties": { "countries": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "posts", "top" ], "type": "object" }, "followers": { "additionalProperties": true, "properties": { "posts": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "status", "posts" ], "type": "object" }, "formats": { "additionalProperties": true, "properties": { "comparisons": { "items": {}, "type": "array" }, "groups": { "items": {}, "type": "array" }, "status": { "type": "string" } }, "required": [ "status", "groups", "comparisons" ], "type": "object" }, "hours": { "additionalProperties": true, "properties": { "eligibleHours": { "items": {}, "type": "array" }, "status": { "type": "string" }, "timeZone": { "type": "string" } }, "required": [ "status", "timeZone", "eligibleHours" ], "type": "object" }, "minimumGroupPosts": { "type": "integer" }, "postCount": { "type": "integer" }, "rankings": { "additionalProperties": true, "properties": { "bottom": { "items": {}, "type": "array" }, "eligible": { "type": "integer" }, "status": { "type": "string" }, "top": { "items": {}, "type": "array" } }, "required": [ "status", "eligible", "top", "bottom" ], "type": "object" }, "simulated": { "type": "boolean" }, "timeZone": { "type": "string" } }, "required": [ "simulated", "timeZone", "postCount", "minimumGroupPosts", "formats", "hours", "followers", "countries", "rankings" ], "type": "object" }, "id": { "type": "string" }, "kind": { "enum": [ "weekly", "on_demand" ], "type": "string" }, "periodEnd": { "type": "string" }, "periodStart": { "type": "string" }, "simulated": { "type": "boolean" }, "text": { "type": "string" } }, "required": [ "id", "accountId", "kind", "periodStart", "periodEnd", "createdAt", "simulated", "text", "findings" ], "type": "object" } } }, "description": "The report." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No such analytics report in this workspace (ANALYTICS_REPORT_NOT_FOUND). Also the answer for a workspace with no analytics module." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "One analytics report of this workspace.", "tags": [ "Analytics" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/approvals": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listApprovals", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "action_requested": { "type": "string" }, "amount_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "decided_at": { "format": "date-time", "nullable": true, "type": "string" }, "decided_by": { "nullable": true, "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "reason": { "nullable": true, "type": "string" }, "requester_role": { "type": "string" }, "status": { "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "entity_type", "entity_id", "action_requested", "amount_cents", "currency", "requester_role", "status", "reason", "decided_by", "decided_at", "expires_at", "created_at" ], "type": "object" }, "type": "array" } } }, "description": "Approval rows, newest first." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Approvals of the workspace. Pending ones past their expiry are expired first.", "tags": [ "Approvals" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/approvals/{approvalId}": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getApproval", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "approvalId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "action_requested": { "type": "string" }, "amount_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "decided_at": { "format": "date-time", "nullable": true, "type": "string" }, "decided_by": { "nullable": true, "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "reason": { "nullable": true, "type": "string" }, "requester_role": { "type": "string" }, "status": { "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "entity_type", "entity_id", "action_requested", "amount_cents", "currency", "requester_role", "status", "reason", "decided_by", "decided_at", "expires_at", "created_at" ], "type": "object" } } }, "description": "The row, as the list returns it." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Approval not found in this workspace (APPROVAL_NOT_FOUND)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "One approval of this workspace.", "tags": [ "Approvals" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/audit": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listAudit", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "action": { "type": "string" }, "actor_id": { "type": "string" }, "actor_type": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "effect_class": { "type": "string" }, "evidence": { "additionalProperties": {}, "type": "object" }, "id": { "type": "string" }, "policy_decision": { "type": "string" }, "tx_hash": { "nullable": true, "type": "string" }, "workflow_id": { "nullable": true, "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "workflow_id", "actor_type", "actor_id", "effect_class", "action", "policy_decision", "evidence", "tx_hash", "created_at" ], "type": "object" }, "type": "array" } } }, "description": "Audit rows." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The 100 newest audit rows. Evidence holds ids and decisions, never secrets.", "tags": [ "Audit" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/connectors": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "listConnectors", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "connectorId": { "type": "string" }, "fingerprint": { "nullable": true, "type": "string" }, "kind": { "enum": [ "messaging", "supplier", "accounting", "llm", "other" ], "type": "string" }, "lastVerifiedAt": { "format": "date-time", "nullable": true, "type": "string" }, "status": { "enum": [ "configured_unverified", "verified", "revoked" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectorId", "kind", "status", "lastVerifiedAt", "fingerprint", "updatedAt" ], "type": "object" }, "type": "array" } } }, "description": "Connector summaries." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The credential store is not configured (BIND_CREDENTIAL_KEY)." } }, "security": [ { "bearerAuth": [] } ], "summary": "Connector credentials, as summaries. A secret is never returned.", "tags": [ "Connectors" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/connectors/{connectorId}": { "delete": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "revokeConnector", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "connectorId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "connectorId": { "type": "string" }, "fingerprint": { "nullable": true, "type": "string" }, "kind": { "enum": [ "messaging", "supplier", "accounting", "llm", "other" ], "type": "string" }, "lastVerifiedAt": { "format": "date-time", "nullable": true, "type": "string" }, "status": { "enum": [ "configured_unverified", "verified", "revoked" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectorId", "kind", "status", "lastVerifiedAt", "fingerprint", "updatedAt" ], "type": "object" } } }, "description": "The revoked summary." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The connector is not found (not configured or already revoked)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The credential store is not configured (BIND_CREDENTIAL_KEY)." } }, "security": [ { "bearerAuth": [] } ], "summary": "Revoke a connector: its ciphertext is destroyed and it is marked revoked.", "tags": [ "Connectors" ], "x-bind-access": "owner" }, "put": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "setConnector", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "connectorId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "kind": { "enum": [ "messaging", "supplier", "accounting", "llm", "other" ], "type": "string" }, "secret": { "maxLength": 8192, "minLength": 1, "type": "string" } }, "required": [ "kind", "secret" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "connectorId": { "type": "string" }, "fingerprint": { "nullable": true, "type": "string" }, "kind": { "enum": [ "messaging", "supplier", "accounting", "llm", "other" ], "type": "string" }, "lastVerifiedAt": { "format": "date-time", "nullable": true, "type": "string" }, "status": { "enum": [ "configured_unverified", "verified", "revoked" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "connectorId", "kind", "status", "lastVerifiedAt", "fingerprint", "updatedAt" ], "type": "object" } } }, "description": "The summary of the stored connector." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The connector id, kind or secret is invalid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The credential store is not configured (BIND_CREDENTIAL_KEY)." } }, "security": [ { "bearerAuth": [] } ], "summary": "Store a connector secret. Accepted once, encrypted at rest, never returned.", "tags": [ "Connectors" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/connectors/{connectorId}/verify": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "verifyConnector", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "connectorId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "connectorId": { "type": "string" }, "status": { "enum": [ "configured_unverified", "verified", "revoked" ], "type": "string" }, "verification": { "enum": [ "NOT_AVAILABLE", "VERIFIED", "FAILED" ], "type": "string" } }, "required": [ "connectorId", "status", "verification" ], "type": "object" } } }, "description": "The verification outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The connector is not found." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The credential store is not configured (BIND_CREDENTIAL_KEY)." } }, "security": [ { "bearerAuth": [] } ], "summary": "Verify a connector against its provider where a verifier exists. Otherwise NOT_AVAILABLE.", "tags": [ "Connectors" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/customer-orders": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listCustomerOrders", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "externalRef": { "type": "string" }, "lines": { "items": { "additionalProperties": true, "properties": { "quantity": { "type": "number" }, "sku": { "type": "string" } }, "required": [ "sku", "quantity" ], "type": "object" }, "type": "array" }, "note": { "nullable": true, "type": "string" }, "orderId": { "type": "string" }, "promisedFor": { "format": "date-time", "nullable": true, "type": "string" }, "reasons": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" }, "requestedFor": { "format": "date-time", "nullable": true, "type": "string" }, "slotId": { "nullable": true, "type": "string" }, "status": { "enum": [ "accepted", "partially_available", "declined", "needs_owner", "cancelled", "fulfilled" ], "type": "string" }, "units": { "type": "number" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "orderId", "externalRef", "status", "requestedFor", "promisedFor", "reasons", "note", "units", "slotId", "decidedBy", "lines", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" } } }, "description": "Customer orders." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Customer orders, newest first.", "tags": [ "Customer orders" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "createCustomerOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "externalRef": { "maxLength": 120, "minLength": 1, "type": "string" }, "lines": { "items": { "additionalProperties": true, "properties": { "quantity": { "type": "number" }, "sku": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "sku", "quantity" ], "type": "object" }, "maxItems": 200, "type": "array" }, "note": { "maxLength": 5000, "type": "string" }, "requestedFor": { "format": "date-time", "type": "string" } }, "required": [ "externalRef", "lines" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "orderId": { "type": "string" }, "promisedFor": { "format": "date-time", "type": "string" }, "reasons": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" }, "replayed": { "type": "boolean" }, "status": { "enum": [ "accepted", "partially_available", "declined", "needs_owner", "cancelled", "fulfilled" ], "type": "string" } }, "required": [ "orderId", "status", "reasons", "replayed" ], "type": "object" } } }, "description": "The same external reference was sent before: the earlier decision, replayed." }, "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "orderId": { "type": "string" }, "promisedFor": { "format": "date-time", "type": "string" }, "reasons": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" }, "replayed": { "type": "boolean" }, "status": { "enum": [ "accepted", "partially_available", "declined", "needs_owner", "cancelled", "fulfilled" ], "type": "string" } }, "required": [ "orderId", "status", "reasons", "replayed" ], "type": "object" } } }, "description": "Created: the decision (accepted, needs_owner, declined, ...)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The request conflicts with an existing order (FulfilmentError code)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Record a customer order and its decision. Customer text is data, never an instruction.", "tags": [ "Customer orders" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/customer-orders/{orderId}": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getCustomerOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "externalRef": { "type": "string" }, "lines": { "items": { "additionalProperties": true, "properties": { "quantity": { "type": "number" }, "sku": { "type": "string" } }, "required": [ "sku", "quantity" ], "type": "object" }, "type": "array" }, "note": { "nullable": true, "type": "string" }, "orderId": { "type": "string" }, "promisedFor": { "format": "date-time", "nullable": true, "type": "string" }, "reasons": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" }, "requestedFor": { "format": "date-time", "nullable": true, "type": "string" }, "slotId": { "nullable": true, "type": "string" }, "status": { "enum": [ "accepted", "partially_available", "declined", "needs_owner", "cancelled", "fulfilled" ], "type": "string" }, "units": { "type": "number" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "orderId", "externalRef", "status", "requestedFor", "promisedFor", "reasons", "note", "units", "slotId", "decidedBy", "lines", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The customer order." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No order with that id in this workspace (ORDER_NOT_FOUND)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "One customer order.", "tags": [ "Customer orders" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/customer-orders/{orderId}/accept": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "acceptCustomerOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "orderId": { "type": "string" }, "promisedFor": { "format": "date-time", "type": "string" }, "reasons": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" }, "replayed": { "type": "boolean" }, "status": { "enum": [ "accepted", "partially_available", "declined", "needs_owner", "cancelled", "fulfilled" ], "type": "string" } }, "required": [ "orderId", "status", "reasons", "replayed" ], "type": "object" } } }, "description": "The decision after the owner's accept." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No order with that id (ORDER_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The order cannot be accepted now." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Accept a held order (the owner decides it; the capacity is checked again).", "tags": [ "Customer orders" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/customer-orders/{orderId}/cancel": { "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "cancelCustomerOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "externalRef": { "type": "string" }, "lines": { "items": { "additionalProperties": true, "properties": { "quantity": { "type": "number" }, "sku": { "type": "string" } }, "required": [ "sku", "quantity" ], "type": "object" }, "type": "array" }, "note": { "nullable": true, "type": "string" }, "orderId": { "type": "string" }, "promisedFor": { "format": "date-time", "nullable": true, "type": "string" }, "reasons": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" }, "requestedFor": { "format": "date-time", "nullable": true, "type": "string" }, "slotId": { "nullable": true, "type": "string" }, "status": { "enum": [ "accepted", "partially_available", "declined", "needs_owner", "cancelled", "fulfilled" ], "type": "string" }, "units": { "type": "number" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "orderId", "externalRef", "status", "requestedFor", "promisedFor", "reasons", "note", "units", "slotId", "decidedBy", "lines", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The order, now cancelled." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No order with that id (ORDER_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The order cannot be cancelled in its state." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancel a customer order. Staff may cancel. Nothing is ordered or paid by this.", "tags": [ "Customer orders" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/customer-orders/{orderId}/fulfil": { "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "fulfilCustomerOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "externalRef": { "type": "string" }, "lines": { "items": { "additionalProperties": true, "properties": { "quantity": { "type": "number" }, "sku": { "type": "string" } }, "required": [ "sku", "quantity" ], "type": "object" }, "type": "array" }, "note": { "nullable": true, "type": "string" }, "orderId": { "type": "string" }, "promisedFor": { "format": "date-time", "nullable": true, "type": "string" }, "reasons": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "sku": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "type": "array" }, "requestedFor": { "format": "date-time", "nullable": true, "type": "string" }, "slotId": { "nullable": true, "type": "string" }, "status": { "enum": [ "accepted", "partially_available", "declined", "needs_owner", "cancelled", "fulfilled" ], "type": "string" }, "units": { "type": "number" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "orderId", "externalRef", "status", "requestedFor", "promisedFor", "reasons", "note", "units", "slotId", "decidedBy", "lines", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The order, now fulfilled." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No order with that id (ORDER_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The order is not accepted (NOT_ACCEPTED) or cannot be fulfilled in its state." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Mark an accepted order fulfilled, and release its reserved stock.", "tags": [ "Customer orders" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/demo/reset": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "resetDemo", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "token": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "workspaceId", "token", "expiresAt" ], "type": "object" } } }, "description": "Created. The new owner token is in the body and is shown only here. Never cached." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Demo workspaces are off on this server (code DEMO_DISABLED)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "This workspace is not a demo (code NOT_A_DEMO). Nothing is changed." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The limit on active demos is reached (code DEMO_CAPACITY_REACHED), or another create holds the lock (code DEMO_BUSY, Retry-After: 3)." } }, "security": [ { "bearerAuth": [] } ], "summary": "Reset a demo: delete it and its data, and return a fresh demo with new credentials. The old token stops working.", "tags": [ "Demo" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/documents": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listDocuments", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "confirmed_at": { "format": "date-time", "nullable": true, "type": "string" }, "confirmed_by": { "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "doc_type": { "type": "string" }, "extracted_data": { "additionalProperties": {}, "type": "object" }, "id": { "type": "string" }, "linked_order_id": { "nullable": true, "type": "string" }, "raw_text": { "type": "string" }, "source_label": { "type": "string" }, "status": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "doc_type", "source_label", "raw_text", "extracted_data", "warnings", "status", "linked_order_id", "confirmed_by", "confirmed_at", "created_at" ], "type": "object" }, "type": "array" } } }, "description": "Staged documents." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The 50 newest staged documents.", "tags": [ "Documents" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/documents/extract": { "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "extractDocument", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "docType": { "enum": [ "quote", "delivery_receipt", "supplier_bill" ], "type": "string" }, "linkedOrderId": { "type": "string" }, "rawText": { "maxLength": 20000, "minLength": 4, "type": "string" }, "sourceLabel": { "default": "manual_upload", "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "docType", "rawText" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "confirmed_at": { "format": "date-time", "nullable": true, "type": "string" }, "confirmed_by": { "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "docId": { "type": "string" }, "docType": { "type": "string" }, "doc_type": { "type": "string" }, "extractedFields": { "additionalProperties": {}, "type": "object" }, "extracted_data": { "additionalProperties": {}, "type": "object" }, "id": { "type": "string" }, "linked_order_id": { "nullable": true, "type": "string" }, "provenance": { "type": "string" }, "raw_text": { "type": "string" }, "source_label": { "type": "string" }, "status": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "doc_type", "source_label", "raw_text", "extracted_data", "warnings", "status", "linked_order_id", "confirmed_by", "confirmed_at", "created_at", "docId", "docType", "provenance", "extractedFields" ], "type": "object" } } }, "description": "The staged draft." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Extract a draft from document text. Staged, never committed.", "tags": [ "Documents" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/documents/{docId}/confirm": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "confirmDocument", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "docId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "billNumber": { "type": "string" }, "linkedOrderId": { "type": "string" }, "quantity": { "exclusiveMinimum": true, "maximum": 1000000, "minimum": 0, "type": "number" }, "sku": { "type": "string" }, "supplierId": { "type": "string" }, "supplierName": { "type": "string" }, "totalPriceCents": { "maximum": 1000000000000, "minimum": 0, "type": "integer" }, "unitPriceCents": { "maximum": 1000000000000, "minimum": 0, "type": "integer" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "docId": { "type": "string" }, "docType": { "type": "string" }, "provenance": { "type": "string" }, "status": { "type": "string" } }, "required": [ "docId", "docType", "status", "provenance" ], "type": "object" } } }, "description": "The confirmed document and what it created." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The document is not staged in this workspace, or the body is invalid." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Confirm a staged document as the owner. The confirming owner is the token label; a body decidedBy is ignored.", "tags": [ "Documents" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/events": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "streamEvents", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "lastEventId", "required": false, "schema": { "pattern": "^\\d{1,19}\\.\\d{1,19}$", "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "An event stream. Frames: `id`, `event`, `data`; `: ping` comments while idle; `event: shutdown` when the server stops; the stream also ends after an hour, when its token is revoked, or on a cap." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid cursor (INVALID_CURSOR): Last-Event-ID or lastEventId is not .." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many event streams (TOO_MANY_STREAMS): the per-token, per-workspace or per-process cap is reached. Retry-After is 5 seconds." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Live stream (text/event-stream) of the workspace's finished audit events. Each event: id (.), event (the audit action) and data (the envelope). Resumes after Last-Event-ID (header) or lastEventId (query); with neither, starts after the latest event.", "tags": [ "Events" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/events/poll": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "pollEvents", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "required": false, "schema": { "pattern": "^\\d{1,19}\\.\\d{1,19}$", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "pattern": "^\\d{1,3}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "events": { "items": { "additionalProperties": true, "properties": { "actor": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "at": { "format": "date-time", "type": "string" }, "correlationId": { "type": "string" }, "data": { "additionalProperties": {}, "type": "object" }, "decision": { "type": "string" }, "effectClass": { "type": "string" }, "id": { "pattern": "^\\d{1,19}\\.\\d{1,19}$", "type": "string" }, "name": { "type": "string" }, "object": { "additionalProperties": true, "properties": { "id": { "nullable": true, "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "id" ], "type": "object" }, "schemaVersion": { "enum": [ 1 ], "type": "number" }, "type": { "type": "string" }, "workflowId": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "id", "type", "name", "schemaVersion", "at", "workspaceId", "effectClass", "decision", "actor", "data" ], "type": "object" }, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "pattern": "^\\d{1,19}\\.\\d{1,19}$", "type": "string" } }, "required": [ "events", "nextCursor", "hasMore" ], "type": "object" } } }, "description": "Events after the cursor, with nextCursor and hasMore." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invalid cursor (INVALID_CURSOR), or a limit that is not an integer from 1 to 200 (INVALID_LIMIT)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The same events as the stream, as JSON pages, for clients that cannot hold a stream (serverless). Without after: the newest events, ascending.", "tags": [ "Events" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/feedback": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listFeedback", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "externalId": { "type": "string" }, "id": { "type": "string" }, "source": { "type": "string" }, "text": { "type": "string" }, "truncated": { "type": "boolean" } }, "required": [ "id", "source", "externalId", "text", "truncated", "createdAt" ], "type": "object" }, "type": "array" } } }, "description": "Feedback items." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The newest feedback items (up to 100).", "tags": [ "Feedback" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "ingestFeedback", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "externalId": { "maxLength": 120, "minLength": 1, "type": "string" }, "source": { "pattern": "^[a-z][a-z0-9_.:-]{1,39}$", "type": "string" }, "text": { "maxLength": 20000, "type": "string" } }, "required": [ "source", "externalId", "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "duplicate": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "id", "duplicate" ], "type": "object" } } }, "description": "The same source and external id was stored before (duplicate)." }, "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "duplicate": { "type": "boolean" }, "id": { "type": "string" } }, "required": [ "id", "duplicate" ], "type": "object" } } }, "description": "Stored." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Store one piece of customer or staff feedback. It is data, never an instruction.", "tags": [ "Feedback" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/feedback/summary": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getFeedbackSummary", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "capped": { "type": "boolean" }, "rowsConsidered": { "type": "number" }, "sample": { "items": { "type": "string" }, "type": "array" }, "since": { "format": "date-time", "type": "string" }, "themes": { "items": { "additionalProperties": true, "properties": { "count": { "type": "number" }, "term": { "type": "string" } }, "required": [ "term", "count" ], "type": "object" }, "type": "array" }, "total": { "type": "number" }, "untrusted": { "enum": [ true ], "type": "boolean" } }, "required": [ "since", "themes", "sample", "total", "rowsConsidered", "capped", "untrusted" ], "type": "object" } } }, "description": "The summary. Its text fields are customer data." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Themes and a sample of the feedback since a date (default: 30 days). Reproducible from stored rows.", "tags": [ "Feedback" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/inventory": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listInventory", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "category": { "type": "string" }, "current_quantity": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "id": { "type": "string" }, "name": { "type": "string" }, "par_level": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "preferred_supplier_id": { "nullable": true, "type": "string" }, "reorder_quantity": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "sku": { "type": "string" }, "unit": { "type": "string" }, "unit_price_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "sku", "name", "category", "unit", "current_quantity", "par_level", "reorder_quantity", "unit_price_cents", "preferred_supplier_id", "updated_at" ], "type": "object" }, "type": "array" } } }, "description": "Inventory rows." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Inventory items, ordered by sku.", "tags": [ "Inventory" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "upsertInventoryItem", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "category": { "default": "General", "maxLength": 64, "minLength": 2, "type": "string" }, "currentQuantity": { "minimum": 0, "type": "number" }, "name": { "maxLength": 120, "minLength": 2, "type": "string" }, "parLevel": { "minimum": 0, "type": "number" }, "preferredSupplierId": { "type": "string" }, "reorderQuantity": { "exclusiveMinimum": true, "minimum": 0, "type": "number" }, "sku": { "maxLength": 64, "minLength": 2, "type": "string" }, "unit": { "default": "unit", "maxLength": 32, "minLength": 1, "type": "string" }, "unitPriceCents": { "minimum": 0, "type": "integer" } }, "required": [ "sku", "name", "currentQuantity", "parLevel", "reorderQuantity", "unitPriceCents" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "category": { "type": "string" }, "current_quantity": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "id": { "type": "string" }, "name": { "type": "string" }, "par_level": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "preferred_supplier_id": { "nullable": true, "type": "string" }, "reorder_quantity": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "sku": { "type": "string" }, "unit": { "type": "string" }, "unit_price_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "sku", "name", "category", "unit", "current_quantity", "par_level", "reorder_quantity", "unit_price_cents", "preferred_supplier_id", "updated_at" ], "type": "object" } } }, "description": "The stored item." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message). Also refused: a workspace whose template has no stock module (code TEMPLATE_HAS_NO_STOCK, ADR 0084)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Add or update an inventory item by sku.", "tags": [ "Inventory" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/invites": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "listInvites", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "createdBy": { "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "revokedAt": { "format": "date-time", "nullable": true, "type": "string" }, "role": { "enum": [ "staff" ], "type": "string" }, "usedAt": { "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "role", "label", "createdBy", "expiresAt", "usedAt", "revokedAt" ], "type": "object" }, "type": "array" } } }, "description": "Invitation summaries." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The workspace's invitations. Never a code.", "tags": [ "People" ], "x-bind-access": "owner" }, "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "createInvite", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "expiresInHours": { "maximum": 336, "minimum": 1, "type": "integer" }, "label": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "label" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "role": { "enum": [ "staff" ], "type": "string" } }, "required": [ "id", "code", "label", "role", "expiresAt" ], "type": "object" } } }, "description": "The invitation. Share the code now: it cannot be shown again." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a single-use staff invitation. The code is returned once and never stored.", "tags": [ "People" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/invites/{inviteId}": { "delete": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "revokeInvite", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "inviteId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "revoked": { "enum": [ true ], "type": "boolean" } }, "required": [ "id", "revoked" ], "type": "object" } } }, "description": "The invitation is revoked." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Invitation not found, already used or already revoked." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Revoke an invitation that has not been used.", "tags": [ "People" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/kitchen-capacity": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listKitchenCapacity", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "capacityUnits": { "type": "number" }, "endsAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "remainingUnits": { "type": "number" }, "startsAt": { "format": "date-time", "type": "string" }, "usedUnits": { "type": "number" } }, "required": [ "id", "startsAt", "endsAt", "capacityUnits", "usedUnits", "remainingUnits" ], "type": "object" }, "type": "array" } } }, "description": "Capacity slots." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Kitchen capacity slots, with the units used and left in each.", "tags": [ "Customer orders" ], "x-bind-access": "member" }, "put": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "setKitchenCapacity", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "slots": { "items": { "additionalProperties": true, "properties": { "capacityUnits": { "minimum": 0, "type": "integer" }, "endsAt": { "format": "date-time", "type": "string" }, "startsAt": { "format": "date-time", "type": "string" } }, "required": [ "startsAt", "endsAt", "capacityUnits" ], "type": "object" }, "maxItems": 200, "minItems": 1, "type": "array" } }, "required": [ "slots" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "capacityUnits": { "type": "number" }, "endsAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "remainingUnits": { "type": "number" }, "startsAt": { "format": "date-time", "type": "string" }, "usedUnits": { "type": "number" } }, "required": [ "id", "startsAt", "endsAt", "capacityUnits", "usedUnits", "remainingUnits" ], "type": "object" }, "type": "array" } } }, "description": "The slots after the change." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace the kitchen capacity slots.", "tags": [ "Customer orders" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/members": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "listMembers", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "accountId": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "joinedAt": { "format": "date-time", "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "accountId", "displayName", "role", "joinedAt" ], "type": "object" }, "type": "array" } } }, "description": "Members." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The people who belong to this workspace, with their roles.", "tags": [ "People" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/members/{accountId}": { "delete": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "removeMember", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "accountId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "accountId": { "type": "string" }, "removed": { "enum": [ true ], "type": "boolean" } }, "required": [ "accountId", "removed" ], "type": "object" } } }, "description": "The member is removed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Member not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The last owner cannot be removed (LAST_OWNER)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove a member and end their sessions. The last owner cannot be removed.", "tags": [ "People" ], "x-bind-access": "owner" }, "put": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "setMemberRole", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "accountId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "accountId": { "type": "string" }, "displayName": { "nullable": true, "type": "string" }, "joinedAt": { "format": "date-time", "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "accountId", "displayName", "role", "joinedAt" ], "type": "object" } } }, "description": "The member with the new role." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Member not found." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The last owner cannot be demoted (LAST_OWNER)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Change a member's role. The last owner cannot be demoted.", "tags": [ "People" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/menu": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listMenu", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "available": { "type": "boolean" }, "description": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "priceCents": { "type": "number" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "description", "priceCents", "available", "updatedAt" ], "type": "object" }, "type": "array" } } }, "description": "Menu items." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The published menu items.", "tags": [ "Menu" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/menu-proposals": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listMenuProposals", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "applied": { "additionalProperties": {}, "nullable": true, "type": "object" }, "change": { "anyOf": [ { "additionalProperties": true, "properties": { "description": { "maxLength": 2000, "type": "string" }, "name": { "maxLength": 400, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "add_item" ], "type": "string" } }, "required": [ "type", "name", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "update_price" ], "type": "string" } }, "required": [ "type", "itemId", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "type": { "enum": [ "remove_item" ], "type": "string" } }, "required": [ "type", "itemId" ], "type": "object" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "proposalId": { "type": "string" }, "proposedBy": { "type": "string" }, "rationale": { "nullable": true, "type": "string" }, "sourceFeedbackIds": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "proposed", "approved", "rejected", "published", "cancelled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "proposalId", "status", "change", "rationale", "sourceFeedbackIds", "proposedBy", "decidedBy", "applied", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" } } }, "description": "Proposals." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Menu proposals, newest first.", "tags": [ "Menu" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "proposeMenuChange", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "change": { "anyOf": [ { "additionalProperties": true, "properties": { "description": { "maxLength": 2000, "type": "string" }, "name": { "maxLength": 400, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "add_item" ], "type": "string" } }, "required": [ "type", "name", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "update_price" ], "type": "string" } }, "required": [ "type", "itemId", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "type": { "enum": [ "remove_item" ], "type": "string" } }, "required": [ "type", "itemId" ], "type": "object" } ] }, "rationale": { "maxLength": 2000, "type": "string" }, "sourceFeedbackIds": { "items": { "maxLength": 64, "minLength": 1, "type": "string" }, "maxItems": 20, "type": "array" } }, "required": [ "change" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "applied": { "additionalProperties": {}, "nullable": true, "type": "object" }, "change": { "anyOf": [ { "additionalProperties": true, "properties": { "description": { "maxLength": 2000, "type": "string" }, "name": { "maxLength": 400, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "add_item" ], "type": "string" } }, "required": [ "type", "name", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "update_price" ], "type": "string" } }, "required": [ "type", "itemId", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "type": { "enum": [ "remove_item" ], "type": "string" } }, "required": [ "type", "itemId" ], "type": "object" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "proposalId": { "type": "string" }, "proposedBy": { "type": "string" }, "rationale": { "nullable": true, "type": "string" }, "sourceFeedbackIds": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "proposed", "approved", "rejected", "published", "cancelled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "proposalId", "status", "change", "rationale", "sourceFeedbackIds", "proposedBy", "decidedBy", "applied", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The proposal, not yet applied." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The menu agent role is not permitted to propose (ROLE_NOT_PERMITTED)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A proposal is refused now, for example while the agents are paused (AGENTS_PAUSED)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Propose a menu change. A staff token proposes as the menu agent (its role and the pause apply).", "tags": [ "Menu" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/menu-proposals/{proposalId}/approve": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "approveMenuProposal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "proposalId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "applied": { "additionalProperties": {}, "nullable": true, "type": "object" }, "change": { "anyOf": [ { "additionalProperties": true, "properties": { "description": { "maxLength": 2000, "type": "string" }, "name": { "maxLength": 400, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "add_item" ], "type": "string" } }, "required": [ "type", "name", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "update_price" ], "type": "string" } }, "required": [ "type", "itemId", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "type": { "enum": [ "remove_item" ], "type": "string" } }, "required": [ "type", "itemId" ], "type": "object" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "proposalId": { "type": "string" }, "proposedBy": { "type": "string" }, "rationale": { "nullable": true, "type": "string" }, "sourceFeedbackIds": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "proposed", "approved", "rejected", "published", "cancelled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "proposalId", "status", "change", "rationale", "sourceFeedbackIds", "proposedBy", "decidedBy", "applied", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The approved proposal." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No proposal with that id (PROPOSAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The proposal is not in a state that can be approved." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Approve a proposal (an owner decision; it is not yet on the menu).", "tags": [ "Menu" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/menu-proposals/{proposalId}/cancel": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "cancelMenuProposal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "proposalId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "applied": { "additionalProperties": {}, "nullable": true, "type": "object" }, "change": { "anyOf": [ { "additionalProperties": true, "properties": { "description": { "maxLength": 2000, "type": "string" }, "name": { "maxLength": 400, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "add_item" ], "type": "string" } }, "required": [ "type", "name", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "update_price" ], "type": "string" } }, "required": [ "type", "itemId", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "type": { "enum": [ "remove_item" ], "type": "string" } }, "required": [ "type", "itemId" ], "type": "object" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "proposalId": { "type": "string" }, "proposedBy": { "type": "string" }, "rationale": { "nullable": true, "type": "string" }, "sourceFeedbackIds": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "proposed", "approved", "rejected", "published", "cancelled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "proposalId", "status", "change", "rationale", "sourceFeedbackIds", "proposedBy", "decidedBy", "applied", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The cancelled proposal." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No proposal with that id (PROPOSAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The proposal cannot be cancelled in its state." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Cancel a proposal that is not yet published.", "tags": [ "Menu" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/menu-proposals/{proposalId}/publish": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "publishMenuProposal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "proposalId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "applied": { "additionalProperties": {}, "nullable": true, "type": "object" }, "change": { "anyOf": [ { "additionalProperties": true, "properties": { "description": { "maxLength": 2000, "type": "string" }, "name": { "maxLength": 400, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "add_item" ], "type": "string" } }, "required": [ "type", "name", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "update_price" ], "type": "string" } }, "required": [ "type", "itemId", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "type": { "enum": [ "remove_item" ], "type": "string" } }, "required": [ "type", "itemId" ], "type": "object" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "proposalId": { "type": "string" }, "proposedBy": { "type": "string" }, "rationale": { "nullable": true, "type": "string" }, "sourceFeedbackIds": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "proposed", "approved", "rejected", "published", "cancelled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "proposalId", "status", "change", "rationale", "sourceFeedbackIds", "proposedBy", "decidedBy", "applied", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The published proposal, with what it changed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No proposal with that id (PROPOSAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The proposal is not approved (NOT_APPROVED)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Publish an approved proposal to the menu. An offer to customers: only an owner may do it.", "tags": [ "Menu" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/menu-proposals/{proposalId}/reject": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "rejectMenuProposal", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "proposalId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "applied": { "additionalProperties": {}, "nullable": true, "type": "object" }, "change": { "anyOf": [ { "additionalProperties": true, "properties": { "description": { "maxLength": 2000, "type": "string" }, "name": { "maxLength": 400, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "add_item" ], "type": "string" } }, "required": [ "type", "name", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "priceCents": { "type": "number" }, "type": { "enum": [ "update_price" ], "type": "string" } }, "required": [ "type", "itemId", "priceCents" ], "type": "object" }, { "additionalProperties": true, "properties": { "itemId": { "maxLength": 64, "minLength": 1, "type": "string" }, "type": { "enum": [ "remove_item" ], "type": "string" } }, "required": [ "type", "itemId" ], "type": "object" } ] }, "createdAt": { "format": "date-time", "type": "string" }, "decidedBy": { "nullable": true, "type": "string" }, "proposalId": { "type": "string" }, "proposedBy": { "type": "string" }, "rationale": { "nullable": true, "type": "string" }, "sourceFeedbackIds": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "proposed", "approved", "rejected", "published", "cancelled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "proposalId", "status", "change", "rationale", "sourceFeedbackIds", "proposedBy", "decidedBy", "applied", "createdAt", "updatedAt" ], "type": "object" } } }, "description": "The rejected proposal." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No proposal with that id (PROPOSAL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The proposal is not in a state that can be rejected." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Reject a proposal.", "tags": [ "Menu" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/needs-attention": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getNeedsAttention", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "capped": { "type": "boolean" }, "items": { "items": { "additionalProperties": true, "properties": { "codes": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "kind": { "type": "string" }, "nextAction": { "type": "string" }, "since": { "format": "date-time", "type": "string" } }, "required": [ "kind", "id", "since", "codes", "nextAction" ], "type": "object" }, "type": "array" } }, "required": [ "items", "capped" ], "type": "object" } } }, "description": "Items that need the owner." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "What the owner must decide: ids, codes and the next action. No customer, supplier or feedback text.", "tags": [ "Workflows" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/notifications": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "getNotificationChannels", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "emailDelivery": { "enum": [ "on", "simulated" ], "type": "string" }, "emails": { "items": { "additionalProperties": true, "properties": { "attemptsRemaining": { "nullable": true, "type": "integer" }, "createdAt": { "format": "date-time", "type": "string" }, "email": { "type": "string" }, "expiresAt": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "pending", "verified" ], "type": "string" }, "verifiedAt": { "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "id", "email", "status", "expiresAt", "verifiedAt", "attemptsRemaining", "createdAt" ], "type": "object" }, "type": "array" } }, "required": [ "emailDelivery", "emails" ], "type": "object" } } }, "description": "Channels." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Whether email notices are on for this server, and the workspace's owner addresses with their status. Never a code.", "tags": [ "Notifications" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/notifications/email": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "requestOwnerEmailVerification", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "email": { "maxLength": 120, "minLength": 3, "type": "string" } }, "required": [ "email" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "email": { "type": "string" }, "expiresAt": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "pending", "verified" ], "type": "string" } }, "required": [ "id", "email", "status", "expiresAt" ], "type": "object" } } }, "description": "The address is already verified for this workspace. Nothing was sent." }, "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "email": { "type": "string" }, "expiresAt": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "pending", "verified" ], "type": "string" } }, "required": [ "id", "email", "status", "expiresAt" ], "type": "object" } } }, "description": "A code was sent and the address is pending." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The address is not a valid email address (INVALID_INPUT)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A demo workspace sends no email (EMAIL_DEMO_REFUSED)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many wrong codes for this address in the last day (EMAIL_ATTEMPTS_EXCEEDED). Nothing was sent." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A send limit is reached (EMAIL_SEND_LIMITED): three codes per address per hour, five addresses or ten codes per workspace per day. Retry-After is set." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The email provider refused or did not answer (EMAIL_SEND_FAILED). Nothing was verified." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Email notices are not set up on this server (EMAIL_NOT_CONFIGURED). Nothing was sent." } }, "security": [ { "bearerAuth": [] } ], "summary": "Send a six-digit code to an address, to be entered at /verify. The code goes only in the email.", "tags": [ "Notifications" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/notifications/email/verify": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "verifyOwnerEmail", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "code": { "pattern": "^\\d{6}$", "type": "string" }, "id": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": [ "id", "code" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "verified" ], "type": "string" }, "verifiedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "email", "status", "verifiedAt" ], "type": "object" } } }, "description": "Verified (also when the address was verified before)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The code is wrong (EMAIL_CODE_INVALID) or not six digits (INVALID_INPUT). The message says how many attempts are left." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A demo workspace verifies no email (EMAIL_DEMO_REFUSED)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No such address on this workspace's list (EMAIL_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The code expired (EMAIL_CODE_EXPIRED), or the code's five attempts or the address's ten wrong guesses in a day are used up (EMAIL_ATTEMPTS_EXCEEDED)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Email notices are not set up on this server (EMAIL_NOT_CONFIGURED)." } }, "security": [ { "bearerAuth": [] } ], "summary": "Check the six-digit code. On success the address receives owner notices.", "tags": [ "Notifications" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/notifications/email/{emailId}": { "delete": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "removeOwnerEmail", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "emailId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "removed": { "enum": [ true ], "type": "boolean" } }, "required": [ "id", "removed" ], "type": "object" } } }, "description": "Removed." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No such address on this workspace's list (EMAIL_NOT_FOUND)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove an owner address. It stops receiving notices at once. The binding it created is removed with it.", "tags": [ "Notifications" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/orders": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listOrders", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "external_order_ref": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "item_name": { "type": "string" }, "item_sku": { "type": "string" }, "match_notes": { "nullable": true, "type": "string" }, "match_status": { "nullable": true, "type": "string" }, "matched_at": { "format": "date-time", "nullable": true, "type": "string" }, "order_number": { "type": "string" }, "quantity": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "settled_amount_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "settled_bill_id": { "nullable": true, "type": "string" }, "settled_receipt_id": { "nullable": true, "type": "string" }, "status": { "type": "string" }, "supplier_id": { "nullable": true, "type": "string" }, "supplier_name": { "type": "string" }, "total_price_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "tx_hash": { "nullable": true, "type": "string" }, "unit_price_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "variance_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "order_number", "supplier_id", "supplier_name", "item_sku", "item_name", "quantity", "unit_price_cents", "total_price_cents", "currency", "status", "idempotency_key", "external_order_ref", "tx_hash", "created_at", "updated_at", "settled_amount_cents", "settled_receipt_id", "settled_bill_id", "match_status", "variance_cents", "match_notes", "matched_at" ], "type": "object" }, "type": "array" } } }, "description": "Order rows." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The 50 newest orders, with the latest three-way match.", "tags": [ "Orders" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/orders/{orderId}": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "external_order_ref": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "item_name": { "type": "string" }, "item_sku": { "type": "string" }, "match_notes": { "nullable": true, "type": "string" }, "match_status": { "nullable": true, "type": "string" }, "matched_at": { "format": "date-time", "nullable": true, "type": "string" }, "order_number": { "type": "string" }, "quantity": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "settled_amount_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "settled_bill_id": { "nullable": true, "type": "string" }, "settled_receipt_id": { "nullable": true, "type": "string" }, "status": { "type": "string" }, "supplier_id": { "nullable": true, "type": "string" }, "supplier_name": { "type": "string" }, "total_price_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "tx_hash": { "nullable": true, "type": "string" }, "unit_price_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "updated_at": { "format": "date-time", "type": "string" }, "variance_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "order_number", "supplier_id", "supplier_name", "item_sku", "item_name", "quantity", "unit_price_cents", "total_price_cents", "currency", "status", "idempotency_key", "external_order_ref", "tx_hash", "created_at", "updated_at", "settled_amount_cents", "settled_receipt_id", "settled_bill_id", "match_status", "variance_cents", "match_notes", "matched_at" ], "type": "object" } } }, "description": "The row, as the list returns it." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Order not found in this workspace (ORDER_NOT_FOUND)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "One supplier order of this workspace, with its latest three-way match.", "tags": [ "Orders" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/policy": { "put": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "updatePolicy", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "approvalThresholdCents": { "minimum": 0, "type": "integer" }, "budgetDailyLimitCents": { "exclusiveMinimum": true, "minimum": 0, "type": "integer" }, "settlementAddress": { "nullable": true, "type": "string" } }, "required": [ "budgetDailyLimitCents", "approvalThresholdCents" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "provenance": { "enum": [ "OWNER_CONFIRMED" ], "type": "string" }, "workspace": { "additionalProperties": true, "properties": { "agents_paused": { "type": "boolean" }, "approval_threshold_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "budget_daily_limit_cents": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "created_at": { "format": "date-time", "type": "string" }, "demo_expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "type": "string" }, "is_demo": { "type": "boolean" }, "name": { "type": "string" }, "settlement_address": { "nullable": true, "type": "string" }, "settlement_mode": { "type": "string" }, "template_id": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "webhook_secret_version": { "type": "integer" } }, "required": [ "id", "name", "template_id", "settlement_address", "settlement_mode", "budget_daily_limit_cents", "approval_threshold_cents", "created_at", "updated_at", "agents_paused", "webhook_secret_version" ], "type": "object" } }, "required": [ "workspace", "provenance" ], "type": "object" } } }, "description": "Updated workspace." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Set the daily budget, the approval threshold and the settlement address.", "tags": [ "Workspaces" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/recover": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "recoverWorkflows", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "details": { "items": { "additionalProperties": true, "properties": { "newState": { "type": "string" }, "previousState": { "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "workflowId", "previousState", "newState" ], "type": "object" }, "type": "array" }, "failedCount": { "type": "number" }, "inDoubt": { "items": { "additionalProperties": true, "properties": { "effectId": { "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "workflowId", "effectId" ], "type": "object" }, "type": "array" }, "recoveredCount": { "type": "number" } }, "required": [ "recoveredCount", "failedCount", "inDoubt", "details" ], "type": "object" } } }, "description": "What was recovered and what is in doubt." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Recover interrupted workflows of this workspace. In-doubt submissions are reported, never resent.", "tags": [ "Workflows" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/replenish": { "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "replenish", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "sku": { "minLength": 1, "type": "string" } }, "required": [ "sku" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "approvalId": { "type": "string" }, "orderId": { "type": "string" }, "state": { "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "workflowId", "state" ], "type": "object" } } }, "description": "The replenishment workflow, and its order or approval if one exists." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character, or a missing or non-text sku. Also refused: a paused workspace (code AGENTS_PAUSED, ADR 0023), a workspace whose template has no stock module (code TEMPLATE_HAS_NO_STOCK, ADR 0084), an unknown sku, and an item with sufficient stock." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Start a replenishment for one sku. Returns the workflow it is in.", "tags": [ "Replenishment" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/suppliers": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listSuppliers", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "adapter_type": { "type": "string" }, "contact_email": { "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "endpoint_url": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "is_simulated": { "type": "boolean" }, "name": { "type": "string" }, "payment_address": { "nullable": true, "type": "string" }, "verified": { "type": "boolean" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "name", "adapter_type", "contact_email", "verified", "is_simulated", "endpoint_url", "created_at", "payment_address" ], "type": "object" }, "type": "array" } } }, "description": "Supplier rows." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Suppliers of the workspace, by name.", "tags": [ "Suppliers" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "upsertSupplier", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "adapterType": { "default": "manual_quote", "enum": [ "simulated_sysco", "simulated_baldor", "rest_api", "manual_quote" ], "type": "string" }, "contactEmail": { "anyOf": [ { "format": "email", "type": "string" }, { "enum": [ "" ], "type": "string" } ] }, "endpointUrl": { "type": "string" }, "id": { "maxLength": 64, "minLength": 2, "type": "string" }, "isSimulated": { "default": true, "type": "boolean" }, "name": { "maxLength": 120, "minLength": 2, "type": "string" }, "paymentAddress": { "nullable": true, "type": "string" }, "verified": { "default": true, "type": "boolean" } }, "required": [ "id", "name" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "adapter_type": { "type": "string" }, "contact_email": { "nullable": true, "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "endpoint_url": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "is_simulated": { "type": "boolean" }, "name": { "type": "string" }, "payment_address": { "nullable": true, "type": "string" }, "verified": { "type": "boolean" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "name", "adapter_type", "contact_email", "verified", "is_simulated", "endpoint_url", "created_at", "payment_address" ], "type": "object" } } }, "description": "The stored supplier." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The supplier id belongs to another workspace. Nothing is changed." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Add or update a supplier. A payee address is checked and stored checksummed.", "tags": [ "Suppliers" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/surfaces": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listSurfaces", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_label": { "nullable": true, "type": "string" }, "actor_role": { "enum": [ "owner", "staff" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "integration_status": { "enum": [ "simulated", "configured_unverified", "verified" ], "type": "string" }, "surface": { "enum": [ "whatsapp", "telegram", "instagram", "slack", "email", "email_magic_link", "pos_webhook", "web_ui" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "surface", "actor_id", "actor_label", "actor_role", "integration_status", "created_at", "updated_at" ], "type": "object" }, "type": "array" } } }, "description": "Bindings." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Identity bindings of messaging surfaces. A binding is the only source of a surface actor's role.", "tags": [ "Surfaces" ], "x-bind-access": "member" }, "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "upsertSurfaceBinding", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "actorId": { "maxLength": 120, "minLength": 2, "type": "string" }, "actorLabel": { "maxLength": 120, "type": "string" }, "actorRole": { "enum": [ "owner", "staff" ], "type": "string" }, "integrationStatus": { "default": "simulated", "enum": [ "simulated", "configured_unverified", "verified" ], "type": "string" }, "surface": { "enum": [ "whatsapp", "telegram", "instagram", "slack", "email", "email_magic_link", "pos_webhook", "web_ui" ], "type": "string" } }, "required": [ "surface", "actorId", "actorRole" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "actor_id": { "type": "string" }, "actor_label": { "nullable": true, "type": "string" }, "actor_role": { "enum": [ "owner", "staff" ], "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "integration_status": { "enum": [ "simulated", "configured_unverified", "verified" ], "type": "string" }, "surface": { "enum": [ "whatsapp", "telegram", "instagram", "slack", "email", "email_magic_link", "pos_webhook", "web_ui" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "surface", "actor_id", "actor_label", "actor_role", "integration_status", "created_at", "updated_at" ], "type": "object" } } }, "description": "The stored binding." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Bind an actor on a surface to a role in this workspace.", "tags": [ "Surfaces" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/tabs": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "listTabs", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "balanceMicro": { "type": "string" }, "counterpartyId": { "type": "string" }, "entryCount": { "type": "number" }, "name": { "type": "string" }, "settleableCents": { "type": "string" } }, "required": [ "counterpartyId", "name", "entryCount", "balanceMicro", "settleableCents" ], "type": "object" }, "type": "array" } } }, "description": "One row per counterparty with entries." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The tabs of the workspace: balance in micro-USDC and the whole cents a settlement would clear now.", "tags": [ "Tabs" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/tabs/charges": { "post": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "recordTabCharge", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "amountMicro": { "maxLength": 64, "type": "string" }, "counterpartyId": { "maxLength": 64, "minLength": 1, "type": "string" }, "description": { "maxLength": 200, "minLength": 1, "type": "string" }, "idempotencyKey": { "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "counterpartyId", "amountMicro", "idempotencyKey", "description" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "created": { "type": "boolean" }, "entry": { "additionalProperties": true, "properties": { "amountMicro": { "type": "string" }, "counterpartyId": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "idempotencyKey": { "type": "string" }, "kind": { "enum": [ "charge", "clear", "reversal" ], "type": "string" }, "settlementId": { "nullable": true, "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "id", "workspaceId", "counterpartyId", "kind", "amountMicro", "idempotencyKey", "settlementId", "description", "createdAt" ], "type": "object" } }, "required": [ "created", "entry" ], "type": "object" } } }, "description": "The same key with the same data was already recorded. Nothing was added." }, "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "created": { "type": "boolean" }, "entry": { "additionalProperties": true, "properties": { "amountMicro": { "type": "string" }, "counterpartyId": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "idempotencyKey": { "type": "string" }, "kind": { "enum": [ "charge", "clear", "reversal" ], "type": "string" }, "settlementId": { "nullable": true, "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "id", "workspaceId", "counterpartyId", "kind", "amountMicro", "idempotencyKey", "settlementId", "description", "createdAt" ], "type": "object" } }, "required": [ "created", "entry" ], "type": "object" } } }, "description": "The charge was recorded." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The amount is not a positive whole number of micro-USDC within the 25 USDC limit (INVALID_CHARGE_AMOUNT), or a field is invalid (INVALID_CHARGE)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The counterparty is not found in your workspace (COUNTERPARTY_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The counterparty is not verified (COUNTERPARTY_NOT_VERIFIED), or the key was used for a different charge (IDEMPOTENCY_CONFLICT)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Record a charge against a counterparty's tab, in micro-USDC (ADR 0081). Settled later in whole cents.", "tags": [ "Tabs" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/tabs/settlements": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "listHeldTabSettlements", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "amountCents": { "type": "string" }, "counterpartyId": { "type": "string" }, "createdAt": { "type": "string" }, "effectStatus": { "nullable": true, "type": "string" }, "hasEffect": { "type": "boolean" }, "holdReason": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "held" ], "type": "string" }, "txHash": { "nullable": true, "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "counterpartyId", "amountCents", "status", "holdReason", "txHash", "createdAt", "updatedAt", "hasEffect", "effectStatus" ], "type": "object" }, "type": "array" } } }, "description": "One row per held settlement, with its hold reason and whether an effect row exists." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The status filter is not held (INVALID_STATUS)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The held tab settlements of the workspace, oldest change first, limited to 50. Read only (docs/decisions/0081).", "tags": [ "Tabs" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/tabs/settlements/{settlementId}/resolve": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "resolveTabSettlement", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "settlementId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "acknowledgeNotSent": { "type": "boolean" }, "action": { "enum": [ "reconcile", "cancel_and_restore" ], "type": "string" } }, "required": [ "action" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "action": { "enum": [ "reconcile", "cancel_and_restore" ], "type": "string" }, "outcome": { "additionalProperties": true, "properties": { "kind": { "type": "string" } }, "required": [ "kind" ], "type": "object" } }, "required": [ "action", "outcome" ], "type": "object" } } }, "description": "The outcome. reconcile: adopted, or why nothing was adopted. cancel_and_restore: cancelled, or already_cancelled on a repeat." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The action is not reconcile or cancel_and_restore (INVALID_ACTION), or acknowledgeNotSent is not a boolean (INVALID_RESOLVE)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The settlement is not found in your workspace (SETTLEMENT_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "A restore is refused as not provably unsent (NOT_PROVABLY_UNSENT), the settlement is not held (SETTLEMENT_NOT_HELD), owns no balance (SETTLEMENT_OWNS_NO_BALANCE), or is being processed (SETTLEMENT_BUSY)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Resolve a held tab settlement: reconcile (adopt and confirm a transfer the ledger or the chain can show) or cancel_and_restore (restore its clear only when it is provably unsent).", "tags": [ "Tabs" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/tabs/{counterpartyId}": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "getTab", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "counterpartyId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "balanceMicro": { "type": "string" }, "counterpartyId": { "type": "string" }, "entries": { "items": { "additionalProperties": true, "properties": { "amountMicro": { "type": "string" }, "counterpartyId": { "type": "string" }, "createdAt": { "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "idempotencyKey": { "type": "string" }, "kind": { "enum": [ "charge", "clear", "reversal" ], "type": "string" }, "settlementId": { "nullable": true, "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "id", "workspaceId", "counterpartyId", "kind", "amountMicro", "idempotencyKey", "settlementId", "description", "createdAt" ], "type": "object" }, "type": "array" }, "settleableCents": { "type": "string" }, "settlements": { "items": { "additionalProperties": true, "properties": { "amountCents": { "type": "string" }, "confirmedAt": { "nullable": true, "type": "string" }, "confirmedBlock": { "nullable": true, "type": "number" }, "counterpartyId": { "type": "string" }, "createdAt": { "type": "string" }, "holdReason": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "status": { "enum": [ "pending", "submitted", "confirmed", "held", "cancelled" ], "type": "string" }, "submittedAt": { "nullable": true, "type": "string" }, "txHash": { "nullable": true, "type": "string" }, "updatedAt": { "type": "string" }, "workspaceId": { "type": "string" } }, "required": [ "id", "workspaceId", "counterpartyId", "amountCents", "status", "txHash", "holdReason", "submittedAt", "confirmedAt", "confirmedBlock", "createdAt", "updatedAt" ], "type": "object" }, "type": "array" } }, "required": [ "counterpartyId", "balanceMicro", "settleableCents", "entries", "settlements" ], "type": "object" } } }, "description": "The tab." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The counterparty is not found in your workspace (COUNTERPARTY_NOT_FOUND)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "One tab: its balance, the latest entries and the latest settlements.", "tags": [ "Tabs" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/tabs/{counterpartyId}/settle": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "settleTab", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "counterpartyId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "amountCents": { "type": "string" }, "balanceMicro": { "type": "string" }, "holdReason": { "nullable": true, "type": "string" }, "outcome": { "enum": [ "below_threshold", "needs_approval", "refused", "settlement", "already_attempted" ], "type": "string" }, "reason": { "type": "string" }, "settlementId": { "type": "string" }, "status": { "enum": [ "pending", "submitted", "confirmed", "held", "cancelled" ], "type": "string" }, "thresholdCents": { "type": "string" }, "txHash": { "nullable": true, "type": "string" }, "utcDay": { "type": "string" } }, "required": [ "outcome" ], "type": "object" } } }, "description": "What the call did: nothing to settle, needs approval, refused, or a settlement with its status." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The counterparty is not found in your workspace (COUNTERPARTY_NOT_FOUND)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Settle the whole cents of a tab now, through the same gates as an order payment (ADR 0081).", "tags": [ "Tabs" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/tokens": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "listTokens", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "revokedAt": { "format": "date-time", "nullable": true, "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "id", "role", "label", "createdAt", "revokedAt" ], "type": "object" }, "type": "array" } } }, "description": "Token summaries." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The tokens of this workspace. Never a hash or a plaintext.", "tags": [ "Tokens" ], "x-bind-access": "owner" }, "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "issueToken", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "label": { "maxLength": 80, "minLength": 1, "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "role", "label" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "role", "label", "token" ], "type": "object" } } }, "description": "The token. Store it now: it cannot be shown again." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The role or label is invalid (INVALID_INPUT)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Issue a token for a role. The plaintext is returned once and never stored.", "tags": [ "Tokens" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/tokens/{tokenId}": { "delete": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "revokeToken", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "tokenId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "id": { "type": "string" }, "label": { "type": "string" }, "revokedAt": { "format": "date-time", "type": "string" }, "role": { "enum": [ "owner", "staff" ], "type": "string" } }, "required": [ "id", "role", "label", "revokedAt" ], "type": "object" } } }, "description": "The revoked token." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No such active token in this workspace (TOKEN_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "It would leave the workspace without an active owner (LAST_OWNER_TOKEN)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Revoke a token. The last active owner token of a workspace cannot be revoked.", "tags": [ "Tokens" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/webhook-secret": { "get": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "getWebhookSecret", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "secret": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "secret", "version" ], "type": "object" } } }, "description": "The current secret and its version." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Webhook signing is not configured (BIND_MASTER_SECRET is unset)." } }, "security": [ { "bearerAuth": [] } ], "summary": "The workspace's surface signing secret. Audited. Sent with Cache-Control: no-store.", "tags": [ "Controls" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/webhook-secret/rotate": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "rotateWebhookSecret", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "secret": { "type": "string" }, "version": { "type": "integer" } }, "required": [ "secret", "version" ], "type": "object" } } }, "description": "The new secret and its version." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Webhook signing is not configured (BIND_MASTER_SECRET is unset)." } }, "security": [ { "bearerAuth": [] } ], "summary": "Rotate the surface signing secret. The old secret stops validating at once.", "tags": [ "Controls" ], "x-bind-access": "owner" } }, "/api/workspaces/{id}/workflows": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "listWorkflows", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "additionalProperties": true, "properties": { "context_data": { "additionalProperties": {}, "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "error_message": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "retry_count": { "type": "integer" }, "state": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "workflow_type": { "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "workflow_type", "state", "context_data", "error_message", "retry_count", "idempotency_key", "created_at", "updated_at" ], "type": "object" }, "type": "array" } } }, "description": "Workflow rows." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workspace not found. The same body answers a workspace that does not exist and one that belongs to another tenant." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "The 50 newest workflows.", "tags": [ "Workflows" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/workflows/{workflowId}": { "get": { "description": "Access: a workspace token of the owner or a staff member of the workspace in the path.", "operationId": "getWorkflow", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "workflowId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "context_data": { "additionalProperties": {}, "type": "object" }, "created_at": { "format": "date-time", "type": "string" }, "error_message": { "nullable": true, "type": "string" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "retry_count": { "type": "integer" }, "state": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "workflow_type": { "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id", "workflow_type", "state", "context_data", "error_message", "retry_count", "idempotency_key", "created_at", "updated_at" ], "type": "object" } } }, "description": "The row, as the list returns it." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Workflow not found in this workspace (WORKFLOW_NOT_FOUND). The same answer for another tenant's id." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "One workflow of this workspace.", "tags": [ "Workflows" ], "x-bind-access": "member" } }, "/api/workspaces/{id}/workflows/{workflowId}/cancel": { "post": { "description": "Access: a workspace token of the owner of the workspace in the path. A staff token gets 403.", "operationId": "cancelWorkflow", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "workflowId", "required": true, "schema": { "type": "string" } }, { "description": "1 to 128 characters from A-Z a-z 0-9 . _ : -. A retry with the same key and the same request returns the first outcome with Idempotent-Replayed: true; a different request is refused with 422 IDEMPOTENCY_KEY_REUSED; a retry while the first is running gets 409 IDEMPOTENCY_IN_PROGRESS. Stored for 24 hours.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "pattern": "^[A-Za-z0-9._:-]{1,128}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "reason": { "maxLength": 200, "type": "string" } }, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "_meta": { "additionalProperties": true, "description": "Outcome of the request in one vocabulary, and what the caller's role may do next.", "properties": { "links": { "additionalProperties": { "type": "string" }, "type": "object" }, "nextActions": { "items": { "additionalProperties": true, "properties": { "actor": { "enum": [ "owner", "staff", "agent", "system" ], "type": "string" }, "href": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "method": { "enum": [ "GET", "POST", "PUT", "DELETE" ], "type": "string" }, "needsConfirmation": { "type": "boolean" } }, "required": [ "id", "label", "actor", "method" ], "type": "object" }, "type": "array" }, "processing": { "additionalProperties": true, "properties": { "events": { "type": "string" }, "poll": { "type": "string" }, "remaining": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "requestId": { "type": "string" }, "state": { "type": "string" }, "status": { "enum": [ "completed", "accepted", "held", "refused" ], "type": "string" }, "warnings": { "items": { "additionalProperties": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "requestId", "status" ], "type": "object" }, "alreadyCancelled": { "type": "boolean" }, "approvalId": { "type": "string" }, "state": { "type": "string" }, "workflowId": { "type": "string" } }, "required": [ "workflowId", "state", "alreadyCancelled" ], "type": "object" } } }, "description": "The workflow, cancelled." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Owner role required." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No workflow with that id (WORKFLOW_NOT_FOUND)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "The workflow cannot be cancelled now (WORKFLOW_NOT_CANCELLABLE or WORKFLOW_STATE_CHANGED)." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Request body too large (over 256 kB)." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication is unavailable (the token lookup failed). Retry later." } }, "security": [ { "bearerAuth": [] } ], "summary": "Owner cancel of a workflow that has not ordered. A pause does not block it; it never orders, pays or contacts a supplier (ADR 0030).", "tags": [ "Workflows" ], "x-bind-access": "owner" } }, "/health": { "get": { "description": "Access: public. No token is needed.", "operationId": "getHealth", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "postgres": { "enum": [ "connected" ], "type": "string" }, "status": { "enum": [ "ok" ], "type": "string" }, "timestamp": { "format": "date-time", "type": "string" } }, "required": [ "status", "postgres", "timestamp" ], "type": "object" } } }, "description": "Alive, and the database answered." }, "500": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "status": { "enum": [ "error" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "The database did not answer. Only the status is returned; the cause is logged." } }, "security": [], "summary": "Liveness: the process answers and the database responds. Carries no data.", "tags": [ "Monitoring" ], "x-bind-access": "public" } }, "/metrics": { "get": { "description": "Access: not a workspace token. Send the operator's metrics token as Authorization: Bearer. A workspace token is refused with 401. The route is disabled (404) when no metrics token is configured.", "operationId": "getMetrics", "responses": { "200": { "description": "Prometheus text exposition." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Malformed JSON, a NUL character in the input, or a field that fails validation (see the route for its own message)." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Authentication required: the token is missing, malformed, unknown or revoked (or the webhook signature is refused)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "No metrics token is configured, so the route is disabled." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "Too many requests: the per-client or per-token limit is reached. Retry-After is set (ADR 0033)." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }, "description": "An unexpected failure. The detail is logged with the request id, never returned." } }, "security": [], "summary": "Prometheus metrics: aggregate counts only (ADR 0032).", "tags": [ "Monitoring" ], "x-bind-access": "metrics-token" } }, "/ready": { "get": { "description": "Access: public. No token is needed.", "operationId": "getReady", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "status": { "enum": [ "ready" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Ready to take traffic." }, "503": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "status": { "enum": [ "not_ready" ], "type": "string" } }, "required": [ "status" ], "type": "object" } } }, "description": "Not ready. No detail is returned." } }, "security": [], "summary": "Readiness: the database answers within the budget and the schema is present.", "tags": [ "Monitoring" ], "x-bind-access": "public" } } }, "servers": [ { "url": "/" } ] }