{ "openapi": "3.1.0", "info": { "title": "Haarness Cloud API", "description": "Public and account API of Haarness Cloud (DESIGN.md §5). Errors use the `ErrorEnvelope` shape.", "version": "v1" }, "paths": { "/.well-known/apple-app-site-association": { "get": { "tags": [ "meta" ], "summary": "The Universal Links file Apple fetches for Haarness for iOS: which of this Cloud's web pages the app opens.", "description": "Auth: public. Built from `HAARNESS_CLOUD_APPLE_APP_IDS`; always JSON (never the web app, never a redirect),\n`Cache-Control: public, max-age=3600`.", "operationId": "apple_app_site_association", "responses": { "200": { "description": "The association file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppleAppSiteAssociation" } } } }, "404": { "description": "This Cloud names no app (`HAARNESS_CLOUD_APPLE_APP_IDS` is unset)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/.well-known/assetlinks.json": { "get": { "tags": [ "meta" ], "summary": "The Digital Asset Links file Android fetches for Haarness for Android: which of this Cloud's web pages the app\nopens (App Links).", "description": "Auth: public. Built from `HAARNESS_CLOUD_ANDROID_APP_LINKS`: one statement per package, `handle_all_urls` with its\nsigning certificates' SHA-256 fingerprints, and the same paths as the iOS file as Android 15+ dynamic app link\ncomponents. Always JSON (never the web app, never a redirect), `Cache-Control: public, max-age=3600`.", "operationId": "android_asset_links", "responses": { "200": { "description": "The statements", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AndroidAssetLinkStatement" } } } } }, "404": { "description": "This Cloud names no app (`HAARNESS_CLOUD_ANDROID_APP_LINKS` is unset)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/account/router-session": { "post": { "tags": [ "router-keys" ], "summary": "Exchange a native OAuth bearer for five-minute inference access.\nRequires the keys scope and builder membership. Revoking the login revokes access immediately.", "operationId": "native_router_session", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeRouterSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Ephemeral session; Cache-Control: no-store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NativeRouterSessionResponse" } } } }, "401": { "description": "Sign-in required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Native session, scope or membership required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts": { "get": { "tags": [ "accounts" ], "summary": "Every account the caller is a member of.", "description": "Auth: `cookie|bearer`.", "operationId": "list_accounts", "responses": { "200": { "description": "The caller's accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_AccountDto" } } } } } }, "post": { "tags": [ "accounts" ], "summary": "Create a team account owned by the caller, with its own billing account.", "description": "Auth: `cookie+csrf|bearer`.", "operationId": "create_account", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountRequest" } } }, "required": true }, "responses": { "201": { "description": "The team account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDto" } } } }, "409": { "description": "`invalid_state`: the caller owns too many teams", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts/{id}": { "get": { "tags": [ "accounts" ], "summary": "One account.", "description": "Auth: `cookie|bearer`. A non-member gets `404`.", "operationId": "get_account", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDto" } } } }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "accounts" ], "summary": "Rename an account.", "description": "Auth: `cookie+csrf|bearer`, role ≥ admin.", "operationId": "patch_account", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequest" } } }, "required": true }, "responses": { "200": { "description": "The account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDto" } } } }, "403": { "description": "Role < admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts/{id}/invitations": { "get": { "tags": [ "accounts" ], "summary": "Pending invitations to a team account.", "description": "Auth: `cookie|bearer`, role ≥ admin.", "operationId": "list_invitations", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending invitations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_InvitationDto" } } } }, "403": { "description": "Role < admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "accounts" ], "summary": "Invite someone by email to a team account; the link is emailed and returned once.", "description": "Auth: `cookie+csrf|bearer`, role ≥ admin. `409 invalid_state` (`details.reason = seats_full`) when every seat of\nthe team's per-seat plan is taken.", "operationId": "create_invitation", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationRequest" } } }, "required": true }, "responses": { "201": { "description": "The invitation and its link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedInvitationDto" } } } }, "409": { "description": "Not a team account, or no free seat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts/{id}/invitations/{invitationId}": { "delete": { "tags": [ "accounts" ], "summary": "Revoke a pending invitation.", "description": "Auth: `cookie+csrf|bearer`, role ≥ admin.", "operationId": "revoke_invitation", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitationId", "in": "path", "description": "Invitation id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Revoked" }, "404": { "description": "Unknown or no longer pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts/{id}/members": { "get": { "tags": [ "accounts" ], "summary": "The members of an account.", "description": "Auth: `cookie|bearer`.", "operationId": "list_members", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_MemberDto" } } } }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts/{id}/members/{userId}": { "delete": { "tags": [ "accounts" ], "summary": "Remove a member, or leave the team (any member may remove themselves).", "description": "Auth: `cookie+csrf|bearer`, role ≥ admin to remove someone else.", "operationId": "remove_member", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "description": "Member user id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" }, "409": { "description": "`invalid_state`: the team would have no owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "accounts" ], "summary": "Change a member's role. Only owners grant or take ownership.", "description": "Auth: `cookie+csrf|bearer`, role ≥ admin.", "operationId": "update_member", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "userId", "in": "path", "description": "Member user id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRequest" } } }, "required": true }, "responses": { "204": { "description": "Updated" }, "409": { "description": "`invalid_state`: the team would have no owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts/{id}/projects": { "get": { "tags": [ "accounts" ], "summary": "The projects of an account.", "description": "Auth: `cookie|bearer`.", "operationId": "list_projects", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_ProjectDto" } } } }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "accounts" ], "summary": "Create a project.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder.", "operationId": "create_project", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } }, "required": true }, "responses": { "201": { "description": "The project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Name taken in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/accounts/{id}/seats": { "get": { "tags": [ "accounts" ], "summary": "A team's seats: what its per-seat plan pays for, members and pending invitations.", "description": "Auth: `cookie|bearer`.", "operationId": "account_seats", "parameters": [ { "name": "id", "in": "path", "description": "Account id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Seats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatsDto" } } } } } } }, "/api/v1/api-keys": { "get": { "tags": [ "accounts" ], "summary": "List account API keys without their secrets. Requires owner/admin membership and a browser session or native OAuth keys scope.", "operationId": "list_account_api_keys", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to your personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Key metadata, including revoked keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_AccountApiKeyDto" } } } }, "401": { "description": "Sign-in required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Account administrator required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "accounts" ], "summary": "Create a scoped account API key. The secret is returned once; idempotency replay returns secretKey=null. Browser mutations require CSRF.", "operationId": "create_account_api_key", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique request key, reused only for retries of the same request", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountApiKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "Created; Cache-Control: no-store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedAccountApiKeyResponse" } } } }, "400": { "description": "Invalid name, permissions or expiry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Account administrator or CSRF required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Active key limit or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/api-keys/{id}": { "delete": { "tags": [ "accounts" ], "summary": "Revoke an account API key and its derived agent tickets. Repeated revocation is safe.", "operationId": "revoke_account_api_key", "parameters": [ { "name": "id", "in": "path", "description": "API key id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "query", "description": "Account owning the key", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Revoked" }, "403": { "description": "Account administrator or CSRF required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Key not found in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "accounts" ], "summary": "Edit an API key's name, capabilities, expiry and model limits. Derived tickets are revoked.", "operationId": "update_account_api_key", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountApiKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountApiKeyDto" } } } }, "400": { "description": "Invalid permissions or expiry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Administrator required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Active key unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/api-keys/{id}/rotate": { "post": { "tags": [ "accounts" ], "summary": "Rotate a key and revoke its derived agent tickets. Expiry and permissions remain unchanged; the replacement secret is shown once.", "operationId": "rotate_account_api_key", "parameters": [ { "name": "id", "in": "path", "description": "API key id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "query", "description": "Account owning the key", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "Unique request key, preserved on retry", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Replacement key; secretKey=null on replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedAccountApiKeyResponse" } } } }, "403": { "description": "Account administrator or CSRF required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Key unavailable or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/attention": { "get": { "tags": [ "attention" ], "summary": "List what waits on a person.", "description": "Open permission requests and questions on the account's connected computers and Cloud workspaces, and chats that\nfinished in the last 24 hours, newest first. Metadata only: open the chat to read and answer a request.\nAuth: scope `workspaces`, any member (viewer). API keys: `workspaces:read`; computer items also need\n`remote:read`. Refresh on the `attention` entity event.", "operationId": "list_attention", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_AttentionItemDto" } } } }, "400": { "description": "Invalid page size or cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/attention/{id}": { "delete": { "tags": [ "attention" ], "summary": "Dismiss a finished chat.", "description": "Marks a `turn_completed`/`turn_failed` item as seen (call it when the person opens the chat); dismissing it again\nis a no-op. A permission or question is resolved only by answering it: `409 invalid_state`.\nAuth: scope `workspaces`, builder; CSRF for cookies. API keys: `workspaces:write` (computer items also\n`remote:read`).", "operationId": "dismiss_attention", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Dismissed" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Not a finished chat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/budgets": { "get": { "tags": [ "billing" ], "summary": "Budgets and what they have spent this period.", "description": "Auth: `cookie|bearer`, role ≥ viewer. `spent` comes from `billing::budget_spent` over the budget's period.", "operationId": "list_budgets", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Budgets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_BudgetDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "billing" ], "summary": "Create a budget over the account, a project or a router key.", "description": "Auth: `cookie+csrf|bearer`, role ∈ {owner, billing}. Always the caller's default account: this route takes\nno `accountId`. The period defaults to the current UTC calendar month.", "operationId": "create_budget", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBudgetRequest" } } }, "required": true }, "responses": { "201": { "description": "The budget, with `spent` at zero", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetDto" } } } }, "400": { "description": "`validation_failed`: unknown `scope`, `scopeId` against the scope rule, a non-positive period, or a negative/out-of-range `limitCredits`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role ∉ {owner, billing}) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/budgets/{id}": { "delete": { "tags": [ "billing" ], "summary": "Delete a budget.", "description": "Auth: `cookie+csrf|bearer`, role ∈ {owner, billing}. A budget of another billing account is indistinguishable\nfrom a missing one.", "operationId": "delete_budget", "parameters": [ { "name": "id", "in": "path", "description": "Budget id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role ∉ {owner, billing}) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown budget", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/checkout": { "post": { "tags": [ "billing" ], "summary": "Open a Stripe Checkout session for a subscription or a top-up.", "description": "Auth: `cookie+csrf|bearer`, role ∈ {owner, billing}. Only webhooks grant; the success redirect does not.\nA replay of the `Idempotency-Key` answers the stored `200` with `Idempotency-Replayed: true` (§5.1).", "operationId": "billing_checkout", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "The checkout URL and the payment operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "400": { "description": "`invalid_request`: unknown plan or top-up code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role ∉ {owner, billing}) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict`: a subscription is already active, or a request with this `Idempotency-Key` is still in flight; `idempotency_mismatch` when the key was used with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`internal`: Stripe rejected the customer or session call", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/entitlements": { "get": { "tags": [ "billing" ], "summary": "The current entitlements of the account.", "description": "Auth: `cookie|bearer`, role ≥ viewer. An account with no open allowance period answers all-zero fields with\n`planCode: null`, never `404`.", "operationId": "billing_entitlements", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entitlements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementsDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/ledger": { "get": { "tags": [ "billing" ], "summary": "The double-entry ledger of the billing account.", "description": "Auth: `cookie|bearer`, role ≥ viewer.", "operationId": "billing_ledger", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1..=200, default 50", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of ledger entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_LedgerEntryDto" } } } }, "400": { "description": "`invalid_cursor`: the cursor does not decode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/payments": { "get": { "tags": [ "billing" ], "summary": "Payments and the Stripe objects they came from.", "description": "Auth: `cookie|bearer`, role ≥ viewer.", "operationId": "billing_payments", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1..=200, default 50", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_PaymentDto" } } } }, "400": { "description": "`invalid_cursor`: the cursor does not decode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/plans": { "get": { "tags": [ "billing" ], "summary": "The plan catalogue, top-ups, cloud classes and the overage rates.", "description": "Auth: public. Served from the catalogue loaded at startup, else from the current `plan_versions` row.", "operationId": "billing_plans", "responses": { "200": { "description": "Plans and top-ups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlansResponse" } } } }, "404": { "description": "`not_found`: no plan version is current", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/portal": { "post": { "tags": [ "billing" ], "summary": "A Stripe billing-portal URL for the account's customer.", "description": "Auth: `cookie+csrf|bearer`, role ∈ {owner, billing}. Accepts an optional `accountId`; defaults to the personal account.", "operationId": "billing_portal", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "The portal URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalResponse" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role ∉ {owner, billing}) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: no Stripe customer yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`internal`: Stripe rejected the portal call", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/subscription": { "get": { "tags": [ "billing" ], "summary": "The current subscription of the account.", "description": "Auth: `cookie|bearer`, role ≥ viewer.", "operationId": "get_subscription", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDto" } } } }, "204": { "description": "No subscription: no plan yet, the trial, or a granted plan" }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/subscription/cancel": { "post": { "tags": [ "billing" ], "summary": "Cancel at period end.", "description": "Auth: `cookie+csrf|bearer`, role ∈ {owner, billing}. Sets `cancel_at_period_end` at Stripe and stores the\nrefreshed object. Accepts an optional `accountId`; defaults to the personal account.", "operationId": "cancel_subscription", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "The updated subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role ∉ {owner, billing}) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: no subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: not bound to Stripe, or already canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`internal`: Stripe rejected the update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/subscription/resume": { "post": { "tags": [ "billing" ], "summary": "Undo a pending cancellation.", "description": "Auth: `cookie+csrf|bearer`, role ∈ {owner, billing}. Accepts an optional `accountId`; defaults to the personal account.", "operationId": "resume_subscription", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "The updated subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role ∉ {owner, billing}) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: no subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: not bound to Stripe, or already canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`internal`: Stripe rejected the update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/usage": { "get": { "tags": [ "billing" ], "summary": "Metered usage items, newest first.", "description": "Auth: `cookie|bearer`, role ≥ viewer. `from` defaults to 30 days ago and `to` to tomorrow.", "operationId": "billing_usage", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Inclusive lower bound; defaults to now − 30 days", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "Exclusive upper bound; defaults to now + 1 day", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1..=200, default 50", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of usage items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_UsageItemDto" } } } }, "400": { "description": "`invalid_cursor`: the cursor does not decode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/billing/wallet": { "get": { "tags": [ "billing" ], "summary": "Balances, overage opt-in and the per-bucket detail.", "description": "Auth: `cookie|bearer`, role ≥ viewer. `heldReserve` counts nanos-unit holds only; unit-second and byte holds\nhave their own fields.", "operationId": "get_wallet", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "billing" ], "summary": "Change overage opt-in.", "description": "Auth: `cookie+csrf|bearer`, role ∈ {owner, billing}. Accepts an optional `accountId`; defaults to the personal account. `UpdateWalletRequest` carries `overageOptIn` only — auto\ntop-up is not settable in v1 — and the answer is the wallet as re-read after the change.", "operationId": "patch_wallet", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWalletRequest" } } }, "required": true }, "responses": { "200": { "description": "The wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role ∉ {owner, billing}) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: no billing account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/capabilities": { "get": { "tags": [ "meta" ], "summary": "The API version and feature list (§5.1 \"Versioning\").", "description": "Auth: public.", "operationId": "capabilities", "responses": { "200": { "description": "Capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" } } } } } } }, "/api/v1/cloud-agents": { "get": { "tags": [ "cloud-agents" ], "summary": "List reusable agent templates.", "operationId": "list_cloud_agents", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CloudAgentDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "cloud-agents" ], "summary": "Save a reusable agent template without allocating compute.", "operationId": "create_cloud_agent", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Reuse on retries", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudAgentDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/cloud-agents/{id}": { "get": { "tags": [ "cloud-agents" ], "summary": "Read an agent template and its public SSH key.", "operationId": "get_cloud_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudAgentDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "put": { "tags": [ "cloud-agents" ], "summary": "Replace an agent template at its expected revision.", "operationId": "update_cloud_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCloudAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudAgentDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "cloud-agents" ], "summary": "Delete a template while preserving existing workspaces.", "operationId": "delete_cloud_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/csrf": { "get": { "tags": [ "identity" ], "summary": "Rotate `sessions.csrf_token`, re-set `hc_csrf` and return the new token.", "description": "Auth: `cookie`.", "operationId": "csrf", "responses": { "200": { "description": "The token to send as `X-CSRF-Token`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CsrfResponse" } } } }, "401": { "description": "No session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/device/{userCode}": { "get": { "tags": [ "identity" ], "summary": "What a device user code is asking for.", "description": "Auth: `cookie`. Rate limited to 10/min per IP.", "operationId": "device_details", "parameters": [ { "name": "userCode", "in": "path", "description": "`XXXX-XXXX`", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The pending authorization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeDetailsResponse" } } } }, "401": { "description": "No session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/device/{userCode}/approve": { "post": { "tags": [ "identity" ], "summary": "Approve a device authorization.", "description": "Auth: `cookie+csrf`.", "operationId": "device_approve", "parameters": [ { "name": "userCode", "in": "path", "description": "`XXXX-XXXX`", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Approved; the client's next poll gets tokens" }, "401": { "description": "No session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: already decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/device/{userCode}/deny": { "post": { "tags": [ "identity" ], "summary": "Deny a device authorization.", "description": "Auth: `cookie+csrf`.", "operationId": "device_deny", "parameters": [ { "name": "userCode", "in": "path", "description": "`XXXX-XXXX`", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Denied" }, "401": { "description": "No session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: already decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/devices": { "get": { "tags": [ "identity" ], "summary": "Browser sessions and native refresh families.", "description": "Auth: `cookie|bearer`.", "operationId": "list_devices", "responses": { "200": { "description": "Sessions and devices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicesResponse" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/devices/{id}": { "delete": { "tags": [ "identity" ], "summary": "Revoke a session or a refresh family. Attach tickets are untouched.", "description": "Auth: `cookie+csrf|bearer`.", "operationId": "revoke_device", "parameters": [ { "name": "id", "in": "path", "description": "Session or device id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not this user's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/events": { "get": { "tags": [ "workspaces" ], "summary": "Account-scoped entity invalidations. Native OAuth uses a bearer header and no Origin;\nbrowsers use session cookies and the configured Origin. Rehydrate REST snapshots on\n`ready/resync_required` and after reconnect. No durable replay cursor is provided.", "operationId": "entity_events", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "WebSocket emitting CloudEntityEvent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudEntityEvent" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Scope or Origin rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/invitations/accept": { "post": { "tags": [ "accounts" ], "summary": "Accept an invitation as the signed-in person (their verified email must be the invited one).", "description": "Auth: `cookie+csrf|bearer`.", "operationId": "accept_invitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitationRequest" } } }, "required": true }, "responses": { "200": { "description": "The team joined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDto" } } } }, "403": { "description": "Signed in with another email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Used, revoked or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: no free seat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/key": { "get": { "tags": [ "accounts" ], "summary": "Introspect the presented API key. Returns only its own account and permissions.", "operationId": "api_key_context", "responses": { "200": { "description": "Key context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyContextDto" } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "API key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/artifacts": { "post": { "tags": [ "marketplace" ], "summary": "Upload a submission archive.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder. The full scan runs in the validation worker.", "operationId": "upload_artifact", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The archive bytes (≤ 256 MiB, streamed)", "content": { "application/zip": { "schema": { "type": "string" } } }, "required": true }, "responses": { "201": { "description": "The stored artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadArtifactResponse" } } } }, "400": { "description": "`validation_failed`: not a usable zip", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Over the upload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/collections": { "get": { "tags": [ "marketplace" ], "summary": "The curated collections.", "description": "Auth: public.", "operationId": "list_collections", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AccountId" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of collections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CollectionRefDto" } } } }, "400": { "description": "`invalid_cursor`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/collections/{slug}": { "get": { "tags": [ "marketplace" ], "summary": "One collection and its resources.", "description": "Auth: public.", "operationId": "get_collection", "parameters": [ { "name": "slug", "in": "path", "description": "Collection slug", "required": true, "schema": { "type": "string" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AccountId" } } ], "responses": { "200": { "description": "The collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDto" } } } }, "404": { "description": "Unknown collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/publishers/{slug}": { "get": { "tags": [ "marketplace" ], "summary": "A publisher and the resources it publishes.", "description": "Auth: public.", "operationId": "get_publisher", "parameters": [ { "name": "slug", "in": "path", "description": "Publisher slug", "required": true, "schema": { "type": "string" } }, { "name": "accountId", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/AccountId" } } ], "responses": { "200": { "description": "The publisher page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublisherPageDto" } } } }, "404": { "description": "Unknown publisher", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/resources": { "get": { "tags": [ "marketplace" ], "summary": "Search the catalogue.", "description": "Auth: public; private listings need `cookie|bearer`.", "operationId": "list_resources", "parameters": [ { "name": "accountId", "in": "query", "description": "Account whose private catalog to include (membership required).", "required": false, "schema": { "$ref": "#/components/schemas/AccountId" } }, { "name": "kind", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ResourceKind" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "collection", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "publisher", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_ResourceSummaryDto" } } } }, "400": { "description": "`invalid_cursor`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/resources/{id}": { "get": { "tags": [ "marketplace" ], "summary": "One resource.", "description": "Auth: public; private listings need `cookie|bearer`.", "operationId": "get_resource", "parameters": [ { "name": "id", "in": "path", "description": "Resource id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceDetailDto" } } } }, "404": { "description": "Unknown or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/resources/{id}/artifact": { "get": { "tags": [ "marketplace" ], "summary": "Download an approved artifact with the same public/private authorization as its resource.", "operationId": "download_marketplace_artifact", "parameters": [ { "name": "id", "in": "path", "description": "Resource id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "query", "description": "Version number; defaults to active version", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Verified catalog archive bytes", "content": { "application/zip": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "404": { "description": "Unknown or inaccessible resource/version/artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "Yanked version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/resources/{id}/install-manifest": { "get": { "tags": [ "marketplace" ], "summary": "What a client needs to install a version: signed artifacts, env placeholders and the lock entry.", "description": "Auth: public; private listings need `cookie|bearer`.", "operationId": "install_manifest", "parameters": [ { "name": "id", "in": "path", "description": "Resource id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "query", "description": "`versionNumber`; the active version when absent", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "allowYanked", "in": "query", "description": "`1` lets an existing installation re-fetch a yanked version", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "`global` (default) or `project`; recorded on the install receipt", "required": false, "schema": { "type": "string" } }, { "name": "client", "in": "query", "description": "The installing client, recorded on the install receipt", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The install manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallManifestDto" } } } }, "404": { "description": "Unknown or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "`gone`: yanked without `allowYanked=1`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/resources/{id}/versions": { "get": { "tags": [ "marketplace" ], "summary": "The versions of a resource.", "description": "Auth: public; private listings need `cookie|bearer`.", "operationId": "list_resource_versions", "parameters": [ { "name": "id", "in": "path", "description": "Resource id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Versions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_VersionSummaryDto" } } } }, "404": { "description": "Unknown or not visible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/submissions": { "post": { "tags": [ "marketplace" ], "summary": "Submit a new resource or a new version.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder.", "operationId": "create_submission", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubmissionRequest" } } }, "required": true }, "responses": { "202": { "description": "The submission, queued for validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionDto" } } } }, "400": { "description": "`validation_failed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`source.artifactId` is unknown or was uploaded by another account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict`: the slug is taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/marketplace/submissions/{id}": { "get": { "tags": [ "marketplace" ], "summary": "One submission and its review state.", "description": "Auth: `cookie|bearer`.", "operationId": "get_submission", "parameters": [ { "name": "id", "in": "path", "description": "Submission id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The submission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmissionDto" } } } }, "404": { "description": "Unknown or not the caller's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/me": { "get": { "tags": [ "identity" ], "summary": "The signed-in user, their accounts and the current session.", "description": "Auth: `cookie|bearer`.", "operationId": "me", "responses": { "200": { "description": "The caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/me/deletion": { "get": { "tags": [ "identity" ], "summary": "What deleting the caller's account would do: the address to type, whether a two-factor code is needed, the\nCloud workspaces destroyed, the plan cancelled, the purchased credits forfeited and each team's outcome.", "description": "Auth: `cookie|bearer` with the `account` scope (not API keys).", "operationId": "account_deletion_preview", "responses": { "200": { "description": "The preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionPreviewDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Missing the `account` scope, or an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "identity" ], "summary": "Delete the caller's account, at once and for good. Every sign-in ends (a browser's cookies are cleared), the\nCloud sessions and their files are destroyed, a paid plan is cancelled and the personal account closes with any\nteam nobody else belongs to; the person leaves their other teams. Invoices, payments and the ledger are kept.", "description": "Auth: `cookie+csrf|bearer` with the `account` scope (not API keys), plus the typed confirmation and, when the\naccount uses two-factor authentication, a current code.", "operationId": "account_deletion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeletionResponse" } } } }, "403": { "description": "Missing the `account` scope, or an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "A team needs another owner first, or the teams changed since the preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The confirmation does not match, or the two-factor code is missing or wrong", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many wrong codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/me/sign-in-methods": { "get": { "tags": [ "identity" ], "summary": "The caller's sign-in methods (Google and Apple identities, the email credential, passkeys), which providers this\nCloud can connect, whether it can hold passkeys, and whether removing one asks for a two-factor code (ADR-0016,\nADR-0017).", "description": "Auth: `cookie|bearer` with the `account` scope (not API keys).", "operationId": "sign_in_methods", "responses": { "200": { "description": "The methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInMethodsDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Missing the `account` scope, or an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/me/sign-in-methods/connect": { "post": { "tags": [ "identity" ], "summary": "Start connecting Google or Apple to the signed-in account: the answer names the provider page to open and sets\nthe login-state cookie. The provider's callback adds the identity to this account and returns to\n`/app/settings?connected=`, or `?connect_error=taken&provider=` when the identity already\nsigns in to another account (accounts are never merged).", "description": "Auth: `cookie+csrf` (browser sessions only).", "operationId": "connect_sign_in_method", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSignInMethodRequest" } } }, "required": true }, "responses": { "200": { "description": "Open `redirectTo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectSignInMethodResponse" } } } }, "400": { "description": "`email` is not a provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not a browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This Cloud does not offer that provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/me/sign-in-methods/passkeys": { "post": { "tags": [ "identity" ], "summary": "Keep the passkey the browser just created. It is named after the password manager that holds it, the account's\naddress is emailed a notice, and the answer is the account's sign-in methods.", "description": "Auth: `cookie+csrf` (browser sessions only).", "operationId": "add_passkey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPasskeyRequest" } } }, "required": true }, "responses": { "200": { "description": "Added; the sign-in methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInMethodsDto" } } } }, "400": { "description": "Not a passkey answer, or for an unknown or expired challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not a browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The passkey already belongs to an account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The passkey did not verify", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/me/sign-in-methods/passkeys/options": { "post": { "tags": [ "identity" ], "summary": "Start adding a passkey to the signed-in account: the options for `navigator.credentials.create()`, valid 10\nminutes. With two-factor authentication on, a current code is required first, since the passkey will sign in\nwithout one.", "description": "Auth: `cookie+csrf` (browser sessions only).", "operationId": "passkey_registration_options", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptionsRequest" } } }, "required": true }, "responses": { "200": { "description": "The creation options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyCreationOptionsDto" } } } }, "403": { "description": "Not a browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This Cloud cannot hold passkeys, or the account has the most it may keep (`details.reason = too_many`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The two-factor code is missing or wrong", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many wrong codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/me/sign-in-methods/{id}/remove": { "post": { "tags": [ "identity" ], "summary": "Remove a Google or Apple identity or a passkey from the caller's account. Google, Apple or email must remain, since\npasskeys alone cannot recover an account. Removing Apple also revokes Haarness's Apple token. Answers the remaining\nmethods.", "description": "Auth: `cookie+csrf` (browser sessions only), plus a current two-factor code when `mfaRequired`.", "operationId": "remove_sign_in_method", "parameters": [ { "name": "id", "in": "path", "description": "The method's id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSignInMethodRequest" } } }, "required": true }, "responses": { "200": { "description": "Removed; the remaining methods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInMethodsDto" } } } }, "403": { "description": "Not a browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such method on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "It is the account's last way to sign in (`details.reason = last_method`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The two-factor code is missing or wrong", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many wrong codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/mfa": { "get": { "tags": [ "identity" ], "summary": "The caller's two-factor authentication.", "description": "Auth: `cookie|bearer`.", "operationId": "mfa_status", "responses": { "200": { "description": "Status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaStatusDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/mfa/disable": { "post": { "tags": [ "identity" ], "summary": "Turn two-factor authentication off: removes the authenticator, recovery codes and trusted browsers.", "description": "Auth: `cookie+csrf` (browser sessions only) plus a current code.", "operationId": "mfa_disable", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaCodeRequest" } } }, "required": true }, "responses": { "204": { "description": "Disabled" }, "422": { "description": "Wrong code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/mfa/recovery-codes": { "post": { "tags": [ "identity" ], "summary": "Replace every recovery code.", "description": "Auth: `cookie+csrf` (browser sessions only) plus a current code.", "operationId": "mfa_recovery_codes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "The new codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaRecoveryCodesResponse" } } } }, "422": { "description": "Wrong code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/mfa/totp/confirm": { "post": { "tags": [ "identity" ], "summary": "Prove the new secret with its first code. Turning two-factor authentication on returns ten recovery codes.", "description": "Auth: `cookie+csrf` (browser sessions only).", "operationId": "mfa_totp_confirm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaConfirmResponse" } } } }, "404": { "description": "No setup in progress, or it expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Wrong code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/mfa/totp/setup": { "post": { "tags": [ "identity" ], "summary": "Generate a new authenticator secret. It replaces nothing until it is confirmed; replacing an enabled\nauthenticator requires a current code.", "description": "Auth: `cookie+csrf` (browser sessions only).", "operationId": "mfa_totp_setup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaSetupRequest" } } }, "required": true }, "responses": { "200": { "description": "The secret for the QR code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaSetupResponse" } } } }, "403": { "description": "Not a browser session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Two-factor authentication is unavailable on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "A current code is required to replace the authenticator", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/mfa/trusted-browsers": { "delete": { "tags": [ "identity" ], "summary": "Make every trusted browser ask for a code again.", "description": "Auth: `cookie+csrf` (browser sessions only).", "operationId": "mfa_forget_browsers", "responses": { "204": { "description": "Forgotten" } } } }, "/api/v1/operations/{id}": { "get": { "tags": [ "workspaces" ], "summary": "One operation.", "description": "Auth: `cookie|bearer`. An operation of another user is a `404`, never a `403`.", "operationId": "get_operation", "parameters": [ { "name": "id", "in": "path", "description": "Operation id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationDto" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown operation, or not the caller's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/operations/{id}/events": { "get": { "tags": [ "workspaces" ], "summary": "Long-poll an operation's events.", "description": "Auth: `cookie|bearer`. Waits up to `waitMs` (clamped to 30000) for an event with `sequence > after`, polling\nevery 250 ms and returning at most 200 events. A timeout is a `200` with an empty `events` array and\n`nextAfter = after`; on a hit the freshly re-read operation is returned alongside. `Last-Event-ID` is not\nread — resume by passing the previous `nextAfter` as `after`.", "operationId": "operation_events", "parameters": [ { "name": "id", "in": "path", "description": "Operation id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "waitMs", "in": "query", "description": "≤ 30000", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "The operation and its new events (possibly empty on a long-poll timeout)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationEventsResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown operation, or not the caller's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/profiles": { "get": { "tags": [ "profiles" ], "summary": "The profile archives of an account.", "description": "Auth: `cookie|bearer`.", "operationId": "list_profiles", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "1..=100", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Profile archives", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_ProfileRecordDto" } } } }, "400": { "description": "`validation_failed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "profiles" ], "summary": "Upload a profile archive.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder. Refusals say only `profile operation refused; check archive,\nlimits, and storage`.", "operationId": "upload_profile", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The archive bytes (≤ 32 MiB)", "content": { "application/zip": { "schema": { "type": "string" } } }, "required": true }, "responses": { "201": { "description": "The stored archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRecordDto" } } } }, "400": { "description": "`validation_failed`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Over the upload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/profiles/{id}": { "get": { "tags": [ "profiles" ], "summary": "One profile archive.", "description": "Auth: `cookie|bearer`.", "operationId": "get_profile", "parameters": [ { "name": "id", "in": "path", "description": "Profile archive id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The archive record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRecordDto" } } } }, "404": { "description": "Unknown or not this account's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "profiles" ], "summary": "Delete a profile archive.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder.", "operationId": "delete_profile", "parameters": [ { "name": "id", "in": "path", "description": "Profile archive id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Unknown or not this account's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/profiles/{id}/download": { "get": { "tags": [ "profiles" ], "summary": "Download a profile archive (`Cache-Control: no-store`).", "description": "Auth: `cookie|bearer`.", "operationId": "download_profile", "parameters": [ { "name": "id", "in": "path", "description": "Profile archive id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The archive bytes", "content": { "application/zip": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown or not this account's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{id}": { "get": { "tags": [ "accounts" ], "summary": "One project.", "description": "Auth: `cookie|bearer`.", "operationId": "get_project", "parameters": [ { "name": "id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "accounts" ], "summary": "Delete a project.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder.", "operationId": "delete_project", "parameters": [ { "name": "id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Still referenced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "accounts" ], "summary": "Rename a project.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder.", "operationId": "patch_project", "parameters": [ { "name": "id", "in": "path", "description": "Project id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "The project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "404": { "description": "Unknown or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Name taken in this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/push/activities/{activityId}": { "put": { "tags": [ "push" ], "summary": "Register a Live Activity's push token.", "description": "A chat the phone follows live: on an iPhone a Live Activity (the id is its `ActivityKit` id, the token its own\npush token), on an Android phone an ongoing notification (`platform: android`, the id the app's, the token the\ndevice's FCM registration token). Cloud updates it while its chat waits on you and ends it when the chat finishes.\nRegistering again refreshes the token. The target must be a computer, shared chat or Cloud workspace of an account\nyou belong to.\nAuth: native bearer token of a sign-in (refresh family) with scope `account`; cookies and API keys get `403`.", "operationId": "register_live_activity", "parameters": [ { "name": "activityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterLiveActivityRequest" } } }, "required": true }, "responses": { "200": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveActivityDto" } } } }, "400": { "description": "Invalid token, environment or target", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not the signed-in app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Target not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The activity ended, or `push_platform_unavailable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Another app's bundle identifier or package name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "push" ], "summary": "Forget a Live Activity.", "description": "Idempotent. Auth: native bearer token of a sign-in, scope `account`.", "operationId": "delete_live_activity", "parameters": [ { "name": "activityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Forgotten" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not the signed-in app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/push/badge": { "get": { "tags": [ "push" ], "summary": "Read the app icon's badge.", "description": "The count the notifications set as the badge, computed the same way: your open approvals and questions that\nyou can answer and a notification told you about, across all your accounts, each once. The app sets its icon\nbadge to it, so the badge never disagrees with the last notification. Requests of a computer that has been\noffline for half a minute are not counted until it is back. Auth: scope `account` (bearer of the app or cookie);\nAPI keys refused.", "operationId": "get_push_badge", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushBadgeDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/push/devices": { "get": { "tags": [ "push" ], "summary": "List the devices that receive your notifications.", "description": "Only devices that can still receive are listed: one whose sign-in was revoked or ran out is left out. `current`\nmarks the device making the request. Auth: scope `account` (cookie or bearer).", "operationId": "list_push_devices", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushDevicesResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/push/devices/current": { "put": { "tags": [ "push" ], "summary": "Register this device for push notifications.", "description": "Stores the push token of the signed-in app making the request, tied to its sign-in: an APNs device token for an\niPhone (`platform: ios`, the default), an FCM registration token for an Android phone (`platform: android`). A new\ntoken replaces the sign-in's previous one, and a token registered before by another sign-in moves here. The token\nis never returned. A platform this Cloud has no push service for is `409 push_platform_unavailable`; `bundleId`\n(Android: the package name, also accepted as `appId`) must be an app this Cloud sends to (`422 unprocessable`\notherwise).\nAuth: native bearer token of a sign-in (refresh family) with scope `account`; cookies and API keys get `403`.", "operationId": "register_push_device", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterPushDeviceRequest" } } }, "required": true }, "responses": { "200": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushDeviceDto" } } } }, "400": { "description": "Invalid token, environment, locale or version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not the signed-in app, or the token lacks the account scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`push_platform_unavailable`: this Cloud sends nothing to this kind of phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Another app's bundle identifier or package name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "push" ], "summary": "Stop push notifications to this device.", "description": "The app calls this before it signs out. Idempotent. Auth: native bearer token of a sign-in, scope `account`.", "operationId": "unregister_push_device", "responses": { "204": { "description": "This device receives no more notifications" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not the signed-in app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/push/devices/current/test": { "post": { "tags": [ "push" ], "summary": "Send a test notification to this device.", "description": "Queues \"Notifications are on\" for this device, at most once every ten seconds.\nAuth: native bearer token of a sign-in, scope `account`.", "operationId": "test_push_device", "responses": { "202": { "description": "Queued" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not the signed-in app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "This device is not registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "A test was sent less than ten seconds ago", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/push/devices/{id}": { "delete": { "tags": [ "push" ], "summary": "Stop notifications to one of your devices.", "description": "Auth: scope `account` (cookie with CSRF, or bearer); only your own devices.", "operationId": "remove_push_device", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/push/preferences": { "get": { "tags": [ "push" ], "summary": "Read your notification settings.", "description": "One switch per category, shared by all your devices (all on until changed). `available` is false when this\nCloud delivers no pushes; `platforms` lists the phones it accepts registrations for (`ios`, `android`).\nAuth: scope `account` (cookie or bearer).", "operationId": "get_push_preferences", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPreferencesDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "push" ], "summary": "Change your notification settings.", "description": "Only the listed categories change. Auth: scope `account` (cookie with CSRF, or bearer).", "operationId": "update_push_preferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePushPreferencesRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPreferencesDto" } } } }, "400": { "description": "Unknown category", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/releases": { "get": { "tags": [ "releases" ], "summary": "The current release manifest of a channel.", "description": "Auth: public.", "operationId": "current_release", "parameters": [ { "name": "channel", "in": "query", "description": "`stable` (default) or `preview`; anything else is `404`", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseManifestResponse" } } } }, "404": { "description": "Unknown channel or no manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/releases/artifacts/{id}": { "get": { "tags": [ "releases" ], "summary": "Download immutable published bytes. Verify x-content-sha256 before execution.", "description": "HEAD answers the headers alone. Content-Location, when present, is the same file on the public release domain\n(Cloudflare's edge).", "operationId": "download_release_artifact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Binary artifact; SHA-256 in x-content-sha256, its public address in Content-Location", "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "404": { "description": "Not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/releases/history": { "get": { "tags": [ "releases" ], "summary": "List published release history, newest first.", "operationId": "release_history", "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Release history", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReleasePublication" } } } } } } } }, "/api/v1/releases/{channel}/chrome-extension/updates.xml": { "get": { "tags": [ "releases" ], "summary": "The update manifest for Haarness for Chrome installed by policy (`ExtensionInstallForcelist`).", "description": "Chrome reads it to find the channel's current signed package (CRX) and its version.", "operationId": "chrome_extension_updates", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "gupdate XML naming the extension ID, the CRX address and its Chrome version", "content": { "application/xml": { "schema": { "type": "string" } } } }, "404": { "description": "No Haarness for Chrome on this channel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/releases/{channel}/{product}": { "get": { "tags": [ "releases" ], "summary": "The release manifest of one product on one channel.", "description": "Auth: public.", "operationId": "product_release", "parameters": [ { "name": "channel", "in": "path", "description": "`stable` or `preview`; anything else is `404`", "required": true, "schema": { "type": "string" } }, { "name": "product", "in": "path", "description": "`cli`, `desktop`, …", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseManifestResponse" } } } }, "404": { "description": "Unknown channel or product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/releases/{channel}/{product}/download": { "get": { "tags": [ "releases" ], "summary": "Select the current or pinned release binary for a platform.", "description": "HEAD answers the headers alone, so an installer learns the SHA-256, version and Content-Location (the file on the\npublic release domain) before downloading. `os` and `arch` are required except for `chrome-extension`, one build\nfor every platform, whose zip is the default (`kind=crx` for the signed package).", "operationId": "download_release", "parameters": [ { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "os", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "arch", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Binary artifact; SHA-256 and version response headers, its public address in Content-Location", "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "400": { "description": "os and arch missing for a per-platform product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Platform or version unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-hosts": { "get": { "tags": [ "remote" ], "summary": "List remote hosts.", "operationId": "list_remote_hosts", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_RemoteHostDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "remote" ], "summary": "Register remote host.", "operationId": "register_remote_host", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRemoteHostRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoteHostDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-hosts/{id}": { "get": { "tags": [ "remote" ], "summary": "Get remote host.", "operationId": "get_remote_host", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoteHostDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "remote" ], "summary": "Revoke remote host.", "operationId": "revoke_remote_host", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "remote" ], "summary": "Update remote host.", "operationId": "update_remote_host", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRemoteHostRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoteHostDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-hosts/{id}/connect": { "get": { "tags": [ "remote" ], "summary": "Native connector only: authenticated WebSocket carrying version 1 bounded relay frames.\nSee docs/REMOTE-ACCESS.md. SDK consumers use remoteHost/remoteSession runtime adapters.", "operationId": "connect_remote_host", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "101": { "description": "Relay WebSocket; native connector protocol" }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-hosts/{id}/runtime/{path}": { "get": { "tags": [ "remote" ], "summary": "Proxies every native /v1 operation, including HTTP writes, SSE and terminal `WebSockets`.\nAppend /v1/host/projects to discover projects, then /v1/host/workspaces/{project}/v1/...\nUse HaarnessCloud.remoteHost(id).workspace(project) in SDKs; remote:control is required.", "operationId": "remote_host", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Native runtime response or event stream" }, "409": { "description": "`conflict`: the computer is offline or its connection changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "`bad_gateway`: the computer is connected but could not complete the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-hosts/{id}/sessions": { "post": { "tags": [ "remote" ], "summary": "Publish remote session.", "operationId": "publish_remote_session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRemoteSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoteSessionDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-sessions": { "get": { "tags": [ "remote" ], "summary": "List remote sessions.", "operationId": "list_remote_sessions", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_RemoteSessionDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-sessions/{id}": { "get": { "tags": [ "remote" ], "summary": "Get remote session.", "operationId": "get_remote_session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoteSessionDto" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "remote" ], "summary": "Unpublish remote session.", "operationId": "unpublish_remote_session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/remote-sessions/{id}/runtime/{path}": { "get": { "tags": [ "remote" ], "summary": "Proxies native /v1 operations within the published conversation tree and shared files.\nSupports HTTP writes and SSE. Host management, PTYs and unrelated chats are denied.\nUse HaarnessCloud.remoteSession(id) in SDKs; remote:control is required.", "operationId": "remote_session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Scoped native runtime response or event stream" }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict`: the computer is offline or its connection changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "`bad_gateway`: the computer is connected but could not complete the request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/reports/ai-output": { "post": { "tags": [ "reports" ], "summary": "Report an agent's reply: why (a fixed reason and an optional note), where it appeared and its text. Google Play\nasks chat apps to let people report offensive AI output without leaving the app; the Haarness apps send it here.", "description": "Auth: `cookie+csrf|bearer` (scope `workspaces`; a member of the chat's account, viewer or above). An API key needs\n`remote:read` for a computer's chat and `workspaces:read` for a Cloud workspace's. `Idempotency-Key` supported. At\nmost 20 reports per person per hour.", "operationId": "report_ai_output", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOutputReportRequest" } } }, "required": true }, "responses": { "201": { "description": "Received", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOutputReportDto" } } } }, "400": { "description": "`validation_failed`: an empty or too long excerpt, note or id, or a place without its id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A token without the `workspaces` scope, an API key without read access to the place, or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such computer, shared chat or Cloud workspace in an account of the caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`idempotency_mismatch`, or the first request with this key is still in flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "20 reports in the last hour (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/router/keys": { "get": { "tags": [ "router-keys" ], "summary": "Compatibility endpoint. Use `GET /api/v1/api-keys` for all application keys.", "description": "Auth: `cookie|bearer`, role ≥ viewer. Revoked keys are omitted and secrets are never returned here.", "operationId": "list_router_keys", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the caller's personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Router keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_RouterKeyDto" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "router-keys" ], "summary": "Compatibility endpoint. Use `POST /api/v1/api-keys` with model capabilities.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder. `secretKey` is returned exactly once and never stored, so an\n`Idempotency-Replayed: true` answer carries `secretKey: null` and the client rotates instead (§5.1).", "operationId": "create_router_key", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRouterKeyRequest" } } }, "required": true }, "responses": { "201": { "description": "The key, its secret and the router base URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedRouterKeyResponse" } } } }, "400": { "description": "`validation_failed`: a `policy.modelAllowlist` entry is not `/`, or a negative/fractional credit limit (§5.3 calls this 422; the handler answers 400)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role < builder) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown account, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict`: a request with this `Idempotency-Key` is still in flight; `idempotency_mismatch` when the key was used with a different body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/router/keys/{keyId}": { "delete": { "tags": [ "router-keys" ], "summary": "Revoke a router key.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder. Always the caller's default account: a key of another account is\nindistinguishable from a missing one.", "operationId": "revoke_router_key", "parameters": [ { "name": "keyId", "in": "path", "description": "Router key id: 16 lowercase hex characters, the `` of `hcr__`", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role < builder) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown key, or not this account's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/router/keys/{keyId}/rotate": { "post": { "tags": [ "router-keys" ], "summary": "Rotate a router key's secret.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder. A new secret under the same `keyId`; the old secret stops working\nat once. Not idempotent: every call mints a new secret.", "operationId": "rotate_router_key", "parameters": [ { "name": "keyId", "in": "path", "description": "Router key id: 16 lowercase hex characters, the `` of `hcr__`", "required": true, "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required of a cookie principal; bearer principals omit it", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "The key and its new secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedRouterKeyResponse" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role < builder) or `csrf_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown key, or not this account's", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/router/model-prices": { "get": { "tags": [ "router-keys" ], "summary": "The published pricebook as model prices.", "description": "Auth: public. Every active tariff of the current pricebook, in USD per million tokens and in credits.", "operationId": "model_prices", "responses": { "200": { "description": "Model prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricesResponse" } } } }, "503": { "description": "`provider_unavailable`: no published pricebook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/router/providers": { "get": { "tags": [ "routers" ], "summary": "Router providers and the settings each one accepts.", "operationId": "router_providers", "responses": { "200": { "description": "Providers available in every environment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouterProvidersResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/routers": { "get": { "tags": [ "routers" ], "summary": "List routers.", "operationId": "list_routers", "parameters": [ { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutersResponse" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "routers" ], "summary": "Create router.", "operationId": "create_router", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRouterRequest" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouterDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/routers/{id}": { "get": { "tags": [ "routers" ], "summary": "Get router.", "operationId": "get_router", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouterDto" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "routers" ], "summary": "Delete router.", "operationId": "delete_router", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "routers" ], "summary": "Update router.", "operationId": "update_router", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRouterRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouterDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/routers/{id}/credentials/{provider}": { "put": { "tags": [ "routers" ], "summary": "Set router credential.", "operationId": "set_router_credential", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRouterCredentialRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouterDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/schedules": { "get": { "tags": [ "cloud-schedules" ], "summary": "Durable Cloud worker scheduling; targets explicit workspace and chat identities.", "operationId": "list_cloud_schedules", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CloudScheduleDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "cloud-schedules" ], "summary": "Durable Cloud worker scheduling; targets explicit workspace and chat identities.", "operationId": "create_cloud_schedule", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCloudScheduleRequest" } } }, "required": true }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudScheduleDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/schedules/preview": { "get": { "tags": [ "cloud-schedules" ], "summary": "Upcoming runs for a cadence, computed by the worker's own rules (time zones and daylight saving included).", "operationId": "preview_cloud_schedule", "parameters": [ { "name": "at", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "everySeconds", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cron", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "How many runs to list (1..20, default 5).", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudSchedulePreviewDto" } } } }, "400": { "description": "Invalid cadence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/schedules/{id}": { "get": { "tags": [ "cloud-schedules" ], "summary": "Durable Cloud worker scheduling; targets explicit workspace and chat identities.", "operationId": "get_cloud_schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudScheduleDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "cloud-schedules" ], "summary": "Durable Cloud worker scheduling; targets explicit workspace and chat identities.", "operationId": "delete_cloud_schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Success" }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "cloud-schedules" ], "summary": "Durable Cloud worker scheduling; targets explicit workspace and chat identities.", "operationId": "update_cloud_schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCloudScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudScheduleDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/schedules/{id}/run": { "post": { "tags": [ "cloud-schedules" ], "summary": "Durable Cloud worker scheduling; targets explicit workspace and chat identities.", "operationId": "run_cloud_schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudScheduleRunDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/schedules/{id}/runs": { "get": { "tags": [ "cloud-schedules" ], "summary": "Durable Cloud worker scheduling; targets explicit workspace and chat identities.", "operationId": "cloud_schedule_runs", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "accountId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_CloudScheduleRunDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/telemetry/usage": { "get": { "tags": [ "telemetry" ], "summary": "The caller's usage statistics, summed over every installation linked to them: per day, top models and tools,\nand the installations.", "description": "Auth: `cookie|bearer` (bearer scope `account`).", "operationId": "usage_summary", "parameters": [ { "name": "days", "in": "query", "description": "1..=366, default 30.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "The caller's statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummaryResponse" } } } }, "400": { "description": "`days` outside 1..=366", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session or token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "A token without the `account` scope, or an API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "telemetry" ], "summary": "Report the usage statistics of a desktop or CLI installation: 1–31 daily snapshots, each replacing what was\nstored for that installation and day.", "description": "Auth: public; an optional `Authorization: Bearer` (a native access token or an API key) links the installation\nto its user. A missing, invalid or expired bearer is anonymous, never `401`, and an anonymous report never\nunlinks an installation. No CSRF. Body ≤ 256 KiB. One accepted report per installation per 60 s.", "operationId": "report_usage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReportRequest" } } }, "required": true }, "responses": { "202": { "description": "Stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageReportResponse" } } } }, "400": { "description": "`invalid_request`: the message names the offending field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Body over 256 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Not `application/json`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "This installation's previous report was accepted less than 60 s ago (`Retry-After`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces": { "get": { "tags": [ "workspaces" ], "summary": "The workspaces of an account, newest first. Every workspace is listed until it is deleted.", "description": "Auth: `cookie|bearer`. Cursor-paginated (§5.1): `{items, nextCursor}`, `limit` 1..=100 (default 50).", "operationId": "list_workspaces", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cloudAgentId", "in": "query", "description": "Only workspaces started from this template", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "description": "`nextCursor` of the previous page", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1..=100, default 50", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of workspaces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_WorkspaceDto" } } } }, "400": { "description": "`invalid_cursor`: the opaque `cursor` did not decode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`unauthenticated`: no session cookie or bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown `accountId`, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "workspaces" ], "summary": "Create a workspace (and, unless `start = false`, start it), blank or from a Cloud agent template.", "description": "Auth: `cookie+csrf|bearer`, role ≥ builder, bearer scope `workspaces`. `cloudAgentId` is optional;\n`configuration` overrides the fields it supplies over the template or the defaults. `initialPrompt` makes Cloud\nsend a first message into a new chat once the workspace is ready (requires start; capability\n`workspace_initial_prompt`); `workspace.launch` reports its chat id and delivery. Answers `202` with the\nworkspace and the `provision` operation; poll `GET /api/v1/operations/{id}/events` for progress.", "operationId": "create_workspace", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1); replays carry `Idempotency-Replayed: true`", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceRequest" } } }, "required": true }, "responses": { "202": { "description": "The workspace and its provision operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperationResponse" } } } }, "400": { "description": "`validation_failed`: `title`, `configuration`, `initialPrompt.*`, or a deprecated field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "`payment_required`, `details.reason = \"no_entitlement\"`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`forbidden` (role < builder), `csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown `accountId`, or the caller is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict` (name taken, or an in-flight key), `concurrency_limit` or `idempotency_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`unprocessable`, `details.reason = \"disk_entitlement\"`: the account's provisioned disk would exceed the entitlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/options": { "get": { "tags": [ "workspaces" ], "summary": "Regions, resource classes and the defaults and limits of the create form.", "description": "Auth: `cookie|bearer`. Static configuration; the `accountId` query is accepted but not used to vary the answer.", "operationId": "workspace_options", "parameters": [ { "name": "accountId", "in": "query", "description": "Defaults to the personal account", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Create-form options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOptionsResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}": { "get": { "tags": [ "workspaces" ], "summary": "One workspace: its settings, runtime status and the delivery of its first message (`launch`).", "description": "Auth: `cookie|bearer`. A workspace of another tenant is a `404`, never a `403`. Every `{id}` also accepts the\nid the workspace had as a Cloud session before the rename.", "operationId": "get_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDto" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "workspaces" ], "summary": "Delete a workspace.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. Asynchronous: the row moves to `Deleting` and the\nreturned operation finishes the teardown.", "operationId": "delete_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "202": { "description": "The delete operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperationResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state` (already deleting), `conflict` (a delete is already queued, or an in-flight key) or `idempotency_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "tags": [ "workspaces" ], "summary": "Rename a workspace, change its settings and write-only environment, or its idle timeout or keep-alive.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. Configuration/environment updates require the current\n`version` and a stopped workspace; supplied maps replace, omitted fields are kept.", "operationId": "patch_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "description": "The workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceDto" } } } }, "400": { "description": "`validation_failed`: `title`, `configuration`, or `idleTimeoutSecs` outside 1..=86400", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict`: a stale `version`, or settings saved while the workspace runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/attach": { "post": { "tags": [ "workspaces" ], "summary": "Mint an attach ticket for the gateway.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. The ticket is bound to the workspace's current ready\ngeneration and expires after `HAARNESS_CLOUD_TICKET_TTL_SECS`.", "operationId": "attach_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Gateway URL, ticket and CLI command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: the workspace is not Running, or it has no ready generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/export": { "post": { "tags": [ "workspaces" ], "summary": "Export a workspace to a downloadable archive.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. Poll the operation, then\n`GET /api/v1/workspaces/{id}/exports/{operationId}/download`.", "operationId": "export_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "202": { "description": "The export operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperationResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict` (an export is already queued, or an in-flight key) or `idempotency_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/exports/{operationId}/download": { "get": { "tags": [ "workspaces" ], "summary": "A presigned URL for a finished export (15 min).", "description": "Auth: `cookie|bearer`. The URL is object-store presigned; the body also carries the archive's size and sha256.", "operationId": "download_export", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operationId", "in": "path", "description": "The export operation", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The presigned URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDownloadResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, an operation of another workspace or another kind, or no completed archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: the export has not succeeded yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "`storage_unavailable`: the object store could not presign the URL (retryable; not in the §5.3 row)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/operations": { "get": { "tags": [ "workspaces" ], "summary": "The operations of a workspace.", "description": "Auth: `cookie|bearer`. Cursor-paginated (§5.1), newest first.", "operationId": "list_workspace_operations", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "1..=200, default 50", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Page_OperationDto" } } } }, "400": { "description": "`invalid_cursor`: the opaque `cursor` did not decode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/restore": { "post": { "tags": [ "workspaces" ], "summary": "Restore a stopped workspace from one of its completed snapshots.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`.", "operationId": "restore_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreRequest" } } }, "required": true }, "responses": { "202": { "description": "The restore operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperationResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or a foreign or incomplete `snapshotId`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state` (the workspace must be Stopped), `conflict` (a restore is already queued) or `idempotency_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/save-agent": { "post": { "tags": [ "workspaces" ], "summary": "Save a workspace's current configuration as an inert template with a fresh SSH key.\nRequires the current workspace version. Environment is copied only when includeEnvironment=true.", "operationId": "save_workspace_agent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveWorkspaceAgentRequest" } } }, "required": true }, "responses": { "201": { "description": "Saved template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudAgentDto" } } } }, "403": { "description": "Permission denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Stale workspace revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/snapshots": { "get": { "tags": [ "workspaces" ], "summary": "The snapshots of a workspace.", "description": "Auth: `cookie|bearer`. Not paginated: every snapshot row, newest first.", "operationId": "list_snapshots", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_SnapshotDto" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "workspaces" ], "summary": "Take a snapshot.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. Allowed in any state; the desired state is untouched.", "operationId": "create_snapshot", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "202": { "description": "The snapshot operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperationResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`conflict` (a snapshot is already queued, or an in-flight key) or `idempotency_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/start": { "post": { "tags": [ "workspaces" ], "summary": "Start a stopped or failed workspace.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. Reserves a running slot against the account's\nentitlement before enqueuing the start job.", "operationId": "start_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "202": { "description": "The start operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperationResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "`payment_required`, `details.reason = \"no_entitlement\"` (§5.3 calls this row `insufficient_credits`; the handler raises `payment_required`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state` (not Stopped/Failed), `concurrency_limit`, `conflict` (a start is already queued) or `idempotency_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/stop": { "post": { "tags": [ "workspaces" ], "summary": "Stop a running or starting workspace.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. Stops with a 10 s grace period.", "operationId": "stop_workspace", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "description": "1..=200 chars (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "202": { "description": "The stop operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperationResponse" } } } }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state` (not Running/Starting), `conflict` (a stop is already queued) or `idempotency_mismatch`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/workspaces/{id}/tickets/revoke": { "post": { "tags": [ "workspaces" ], "summary": "Revoke every attach ticket of a workspace.", "description": "Auth: `cookie+csrf|bearer`, bearer scope `workspaces`. Idempotent: revoking twice is still `204`.", "operationId": "revoke_workspace_tickets", "parameters": [ { "name": "id", "in": "path", "description": "Workspace id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required for the cookie auth mode (§5.1)", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "204": { "description": "Revoked" }, "401": { "description": "`unauthenticated`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`csrf_mismatch` or `insufficient_scope`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`not_found`: unknown workspace, or not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/apple/callback": { "get": { "tags": [ "identity" ], "summary": "Finish Sign in with Apple: creates the user on first login and sets `hc_session` + `hc_csrf`, or asks for the\nsecond factor.", "description": "Auth: public (the `state` is the credential, bound to the browser by its cookie). Errors render\n`login_error.html`.", "operationId": "apple_callback", "parameters": [ { "name": "code", "in": "query", "description": "Authorization code", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Opaque state of the login attempt", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to `{web_origin}{return_to}` or the second-factor page" }, "400": { "description": "Replayed or unknown state, or another browser", "content": { "text/html": {} } }, "401": { "description": "Apple refused the code, or the identity token is not valid", "content": { "text/html": {} } } } }, "post": { "tags": [ "identity" ], "summary": "Apple's form post: keeps the name the person shared (first sign-in only) on the attempt, then sends the browser\nto the GET below, which carries its login-state cookie.", "description": "Auth: public (the `state` is the credential).", "operationId": "apple_callback_post", "requestBody": { "description": "`code`, `state`, `user`, or `error`", "content": { "application/x-www-form-urlencoded": {} } }, "responses": { "303": { "description": "Redirect to `GET /auth/apple/callback?code&state`" } } } }, "/auth/apple/start": { "get": { "tags": [ "identity" ], "summary": "Start Sign in with Apple (when `HAARNESS_CLOUD_APPLE_SIGNIN_*` configures it; `/auth/options` says `appleEnabled`).", "description": "Auth: public. Redirects to Apple with `response_mode=form_post`.", "operationId": "apple_start", "parameters": [ { "name": "return_to", "in": "query", "description": "Relative path, sanitised to `/app` when unsafe", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to Apple's authorization endpoint" }, "409": { "description": "Sign in with Apple is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/connect": { "get": { "tags": [ "identity" ], "summary": "The first Google or Apple sign-in waiting in this browser (`hc_link` cookie) because its verified address already\nbelongs to an account: the sign-in page offers that account's methods, which take the new identity along.", "description": "Auth: public (the `hc_link` cookie).", "operationId": "pending_sign_in", "responses": { "200": { "description": "What waits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingSignInDto" } } } }, "404": { "description": "Nothing waits in this browser, or it expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/connect/cancel": { "post": { "tags": [ "identity" ], "summary": "Forget the waiting identity.", "description": "Auth: public (the `hc_link` cookie), from the Haarness sign-in page (exact `Origin`).", "operationId": "pending_sign_in_cancel", "responses": { "204": { "description": "Forgotten" }, "403": { "description": "Not from the sign-in page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/connect/separate": { "post": { "tags": [ "identity" ], "summary": "Use the waiting identity for a new, separate account instead, and sign in to it.", "description": "Auth: public (the `hc_link` cookie), from the Haarness sign-in page (exact `Origin`).", "operationId": "pending_sign_in_separate", "responses": { "200": { "description": "Signed in, or the second factor is next", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponse" } } } }, "403": { "description": "Not from the sign-in page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Nothing waits in this browser, or it expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/email/confirm": { "post": { "tags": [ "identity" ], "summary": "Sign in with an emailed link, or a code with the address it was sent to (creating the account for a new address);\nsets `HttpOnly` session and CSRF cookies.", "operationId": "email_confirm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailConfirmRequest" } } }, "required": true }, "responses": { "200": { "description": "`redirectTo` continuation, or `mfaRequired` with an `HttpOnly` `hc_mfa` cookie when the account uses two-factor authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponse" } } } }, "400": { "description": "Invalid, expired or used link, or a code without its address" }, "401": { "description": "No code for this address is waiting in this browser" }, "422": { "description": "Wrong code" }, "429": { "description": "Rate limited" } } } }, "/auth/email/forgot-password": { "post": { "tags": [ "identity" ], "summary": "Request a one-use link to set or reset the password. Requires configured web Origin and JSON.", "operationId": "email_forgot", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAccountRequest" } } }, "required": true }, "responses": { "200": { "description": "Same message for known and unknown email addresses" }, "429": { "description": "Rate limited: this network, or the service's hourly email budget" } } } }, "/auth/email/link": { "post": { "tags": [ "identity" ], "summary": "Describe an emailed sign-in link without using it: whose it is and whether this browser asked for it.", "operationId": "email_link", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLinkRequest" } } }, "required": true }, "responses": { "200": { "description": "The link's address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLinkResponse" } } } }, "400": { "description": "Invalid, expired or used link" } } } }, "/auth/email/login": { "post": { "tags": [ "identity" ], "summary": "Sign in with a verified Haarness email credential; sets `HttpOnly` session and CSRF cookies.", "operationId": "email_login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailLoginRequest" } } }, "required": true }, "responses": { "200": { "description": "`redirectTo` continuation, or `mfaRequired` with an `HttpOnly` `hc_mfa` cookie when the account uses two-factor authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponse" } } } }, "401": { "description": "Incorrect email or password" }, "429": { "description": "Rate limited" } } } }, "/auth/email/reset-password": { "post": { "tags": [ "identity" ], "summary": "Consume reset link, set the password (also the first one for an account made by email link) and revoke existing\nsessions/native credentials. Then sign in explicitly.", "operationId": "email_reset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailPasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Password saved; returnTo and message" }, "400": { "description": "Invalid, expired or used link" } } } }, "/auth/email/start": { "post": { "tags": [ "identity" ], "summary": "Continue with email: mails a sign-in link and 6-digit code, or for a new address a link that creates the account.\nRequires the configured web Origin and JSON. Creates no account yet. Sets the `HttpOnly` `hc_email` cookie that the\ncode only works with.", "operationId": "email_start", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAccountRequest" } } }, "required": true }, "responses": { "200": { "description": "Check your inbox, independent of account existence" }, "429": { "description": "Rate limited: this network, or the service's hourly email budget" }, "503": { "description": "Email could not be sent" } } } }, "/auth/google/callback": { "get": { "tags": [ "identity" ], "summary": "Google OIDC callback: creates the user on first login and sets `hc_session` + `hc_csrf`.", "description": "Auth: public (the `state` is the credential). Errors render `login_error.html`.", "operationId": "google_callback", "parameters": [ { "name": "code", "in": "query", "description": "Authorization code", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Opaque state of the login attempt", "required": true, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to `{web_origin}{return_to}`" }, "400": { "description": "Replayed or unknown state", "content": { "text/html": {} } }, "401": { "description": "Wrong issuer, audience, signature or nonce", "content": { "text/html": {} } } } } }, "/auth/google/start": { "get": { "tags": [ "identity" ], "summary": "Start the Google OIDC login.", "description": "Auth: public. Redirects to Google; the callback lands on `{web_origin}{return_to}`.", "operationId": "google_start", "parameters": [ { "name": "return_to", "in": "query", "description": "Relative path, sanitised to `/app` when unsafe", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the Google authorization endpoint" } } } }, "/auth/logout": { "post": { "tags": [ "identity" ], "summary": "Revoke the current session and clear the cookies.", "description": "Auth: `cookie+csrf`.", "operationId": "logout", "responses": { "204": { "description": "Logged out" }, "401": { "description": "No session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/logout-all": { "post": { "tags": [ "identity" ], "summary": "Revoke every session, refresh family and attach ticket of the user.", "description": "Auth: `cookie+csrf`.", "operationId": "logout_all", "responses": { "204": { "description": "Logged out everywhere" }, "401": { "description": "No session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/mfa": { "get": { "tags": [ "identity" ], "summary": "The sign-in waiting for its code in this browser (the `hc_mfa` cookie).", "description": "Auth: public (the `HttpOnly` challenge cookie is the credential).", "operationId": "mfa_challenge", "responses": { "200": { "description": "The waiting sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaChallengeDto" } } } }, "401": { "description": "No sign-in is waiting, or it expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/mfa/cancel": { "post": { "tags": [ "identity" ], "summary": "Abandon the waiting sign-in and clear `hc_mfa`.", "description": "Auth: public. Requires the configured web Origin.", "operationId": "mfa_cancel", "responses": { "204": { "description": "Cancelled" } } } }, "/auth/mfa/verify": { "post": { "tags": [ "identity" ], "summary": "Finish a sign-in with an authenticator or recovery code; sets `hc_session` + `hc_csrf`, and `hc_mfa_trust`\nwhen `trustBrowser` is set.", "description": "Auth: public with the `hc_mfa` cookie. Requires the configured web Origin and JSON. Five wrong codes end the\nsign-in; ten per account per 15 minutes are allowed.", "operationId": "mfa_verify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "`redirectTo` continuation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponse" } } } }, "401": { "description": "No sign-in is waiting, it expired, or too many wrong codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Wrong, reused or malformed code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/options": { "get": { "tags": [ "identity" ], "summary": "Available account login methods for this deployment.", "operationId": "auth_options", "responses": { "200": { "description": "googleEnabled, appleEnabled, emailEnabled and passkeyEnabled" } } } }, "/auth/passkey/finish": { "post": { "tags": [ "identity" ], "summary": "Finish a sign-in with a passkey: verifies the browser's answer and creates the session (`hc_session` + `hc_csrf`).\nA passkey is a second factor on its own, so two-factor authentication asks for no code here. A Google or Apple\nsign-in waiting in this browser for this account joins it, as at every sign-in (ADR-0016).", "description": "Auth: public, from the Haarness sign-in page (exact `Origin`).", "operationId": "passkey_sign_in", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeySignInRequest" } } }, "required": true }, "responses": { "200": { "description": "Signed in; continue to `redirectTo`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponse" } } } }, "400": { "description": "Not a passkey answer, or for an unknown or expired challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No account has this passkey (`details.reason = unknown_passkey`), or it did not verify", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Not from the sign-in page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many sign-in requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/passkey/options": { "post": { "tags": [ "identity" ], "summary": "Start a sign-in with a passkey (ADR-0017): a fresh challenge for `navigator.credentials.get()`, valid 10 minutes.\nNo address is asked for: the browser lists this site's passkeys, and the sign-in page also offers them in the\nemail field's autofill.", "description": "Auth: public, from the Haarness sign-in page (exact `Origin`).", "operationId": "passkey_sign_in_options", "responses": { "200": { "description": "The request options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyRequestOptionsDto" } } } }, "403": { "description": "Not from the sign-in page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This Cloud's web origin cannot hold passkeys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Too many sign-in requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/device": { "get": { "tags": [ "identity" ], "summary": "The page a user opens to type the device user code.", "description": "Auth: public (the page itself; its API calls need a session).", "operationId": "device_page", "parameters": [ { "name": "user_code", "in": "query", "description": "Prefilled by `verification_uri_complete`", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The device page", "content": { "text/html": {} } } } } }, "/healthz": { "get": { "tags": [ "meta" ], "summary": "Liveness.", "description": "Auth: public.", "operationId": "healthz", "responses": { "200": { "description": "The process is up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/install.ps1": { "get": { "tags": [ "releases" ], "summary": "Windows CLI and Desktop installer.", "operationId": "release_install_ps1", "responses": { "200": { "description": "Installer script", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/install.sh": { "get": { "tags": [ "releases" ], "summary": "POSIX CLI and Desktop installer.", "operationId": "release_install_sh", "responses": { "200": { "description": "Installer script", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/internal/ops/jobs/dead": { "get": { "tags": [ "internal" ], "summary": "The dead-letter jobs.", "description": "Auth: `internal` (an ops route, available in every environment).", "operationId": "internal_dead_jobs", "responses": { "200": { "description": "Dead jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Items_DeadJobDto" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/ops/jobs/{id}/retry": { "post": { "tags": [ "internal" ], "summary": "Requeue a dead job.", "description": "Auth: `internal` (an ops route, available in every environment).", "operationId": "internal_retry_job", "parameters": [ { "name": "id", "in": "path", "description": "Job id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "The requeued job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadJobDto" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown or not dead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/ops/ledger-check": { "get": { "tags": [ "internal" ], "summary": "Compare every bucket balance with the ledger (`billing::verify_ledger`).", "description": "Auth: `internal` (an ops route, available in every environment).", "operationId": "internal_ledger_check", "parameters": [ { "name": "billingAccountId", "in": "query", "description": "The billing account to verify", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The mismatches, empty when the ledger agrees", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerCheckResponse" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown billing account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/ops/marketplace/versions/{id}/review": { "post": { "tags": [ "internal" ], "summary": "Approve, reject or yank a marketplace version.", "description": "Auth: `internal` (moderation is ours, not the publisher's; available in every environment).", "operationId": "internal_review_version", "parameters": [ { "name": "id", "in": "path", "description": "Version id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewVersionRequest" } } }, "required": true }, "responses": { "200": { "description": "The reviewed version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewVersionResponse" } } } }, "400": { "description": "`validation_failed`: a `yanked` decision without `notes`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/ops/reports/ai-output": { "get": { "tags": [ "internal" ], "summary": "Reports of agents' replies for review, newest first, with the reply's text and the open count.", "description": "Auth: `internal` (an ops route, available in every environment; the metrics token does not open it).", "operationId": "internal_ai_output_reports", "parameters": [ { "name": "status", "in": "query", "description": "`open` (the default), `resolved` or `all`.", "required": false, "schema": { "$ref": "#/components/schemas/AiOutputReportStatus" } }, { "name": "cursor", "in": "query", "description": "The `nextCursor` of the previous page.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "1–200, default 50.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "A page of reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOutputReportsOpsResponse" } } } }, "400": { "description": "`limit` outside 1..=200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/ops/reports/ai-output/{id}/resolve": { "post": { "tags": [ "internal" ], "summary": "Mark a report reviewed, with what was done about it.", "description": "Auth: `internal`.", "operationId": "internal_resolve_ai_output_report", "parameters": [ { "name": "id", "in": "path", "description": "Report id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveAiOutputReportRequest" } } }, "required": true }, "responses": { "200": { "description": "Resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiOutputReportOpsDto" } } } }, "400": { "description": "`validation_failed`: an empty or too long resolution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: resolved already", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/ops/telemetry/usage": { "get": { "tags": [ "internal" ], "summary": "Usage statistics across every installation: per-day totals, top models and tools, client versions, operating\nsystems and the 50 users with the most tokens (user ids, never emails).", "description": "Auth: `internal` (an ops route, available in every environment; the metrics token does not open it).", "operationId": "internal_usage_summary", "parameters": [ { "name": "days", "in": "query", "description": "1..=366, default 30.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Totals across everyone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageOpsResponse" } } } }, "400": { "description": "`days` outside 1..=366", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/ops/users/{id}/mfa/reset": { "post": { "tags": [ "internal" ], "summary": "Turn two-factor authentication off for a user who lost both their authenticator and recovery codes, after\nsupport confirmed who they are. Sessions are untouched; the user is notified by email.", "description": "Auth: `internal`.", "operationId": "internal_mfa_reset", "parameters": [ { "name": "id", "in": "path", "description": "User id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Two-factor authentication is off" }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Two-factor authentication was not on", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/releases": { "post": { "tags": [ "internal" ], "summary": "Publish uploaded artifacts atomically to a release channel.", "operationId": "publish_release", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishReleaseRequest" } } }, "required": true }, "responses": { "200": { "description": "Published release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePublication" } } } }, "401": { "description": "Internal token required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Immutable version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/releases/artifacts": { "post": { "tags": [ "internal" ], "summary": "Upload a private immutable payload with a required checksum and byte length.", "operationId": "upload_release_artifact", "parameters": [ { "name": "version", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "product", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "file", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "os", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "arch", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "x-content-sha256", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "content-length", "in": "header", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } }, "required": true }, "responses": { "200": { "description": "Registered upload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseUpload" } } } }, "401": { "description": "Internal token required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Immutable artifact conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/releases/{id}": { "delete": { "tags": [ "internal" ], "summary": "Withdraw a publication. The channel remains empty if it was current.", "operationId": "withdraw_release", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Withdrawn" }, "401": { "description": "Internal token required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/releases/{id}/promote": { "post": { "tags": [ "internal" ], "summary": "Promote a historical release on its original channel (explicit rollback).", "operationId": "promote_release", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Promoted release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePublication" } } } }, "401": { "description": "Internal token required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown or withdrawn release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/test/drain-bucket": { "post": { "tags": [ "internal" ], "summary": "Drain a bucket down to `leave` nanos.", "description": "Auth: `internal`, and only when `HAARNESS_CLOUD_FIXTURES=1` (else `404`).", "operationId": "internal_drain_bucket", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrainBucketRequest" } } }, "required": true }, "responses": { "200": { "description": "The drained bucket and the transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrainBucketResponse" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Unknown billing account or bucket, or `HAARNESS_CLOUD_FIXTURES` is off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`invalid_state`: the bucket already holds at most `leave`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/test/enqueue-job": { "post": { "tags": [ "internal" ], "summary": "Enqueue a job.", "description": "Auth: `internal`, and only when `HAARNESS_CLOUD_FIXTURES=1` (else `404`).", "operationId": "internal_enqueue_job", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueJobRequest" } } }, "required": true }, "responses": { "202": { "description": "The job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueJobResponse" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`HAARNESS_CLOUD_FIXTURES` is off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/internal/test/grant": { "post": { "tags": [ "internal" ], "summary": "Grant a plan period to a billing account, so an area has a funded account before Stripe exists.", "description": "Auth: `internal`, and only when `HAARNESS_CLOUD_FIXTURES=1` (else `404`).", "operationId": "internal_grant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantTestRequest" } } }, "required": true }, "responses": { "200": { "description": "The period, entitlements and buckets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantTestResponse" } } } }, "400": { "description": "Unknown plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or wrong internal token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`HAARNESS_CLOUD_FIXTURES` is off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/oauth/authorize": { "get": { "tags": [ "identity" ], "summary": "The native PKCE consent page.", "description": "Auth: `cookie` (no session → redirect to the Haarness sign-in page, which returns here).", "operationId": "oauth_authorize_get", "parameters": [ { "name": "response_type", "in": "query", "description": "`code`", "required": false, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "description": "`haarness-cli`", "required": false, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "description": "Loopback redirect of the client", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "description": "Space-separated subset of the allowed scopes", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Opaque client state", "required": false, "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "description": "base64url(sha256(verifier))", "required": false, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "description": "`S256`", "required": false, "schema": { "type": "string" } }, { "name": "request", "in": "query", "description": "An OAuth request resumed after login", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The consent page", "content": { "text/html": {} } }, "302": { "description": "Redirect to the login, or straight back to `redirect_uri`" }, "400": { "description": "Unknown client, redirect or method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "identity" ], "summary": "Approve or deny a native PKCE consent.", "description": "Auth: `cookie+csrf` (JSON body plus `X-CSRF-Token`, or the form the consent page posts).", "operationId": "oauth_authorize_post", "requestBody": { "description": "The decision and the request id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentDecisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Where the client should be sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentDecisionResponse" } } } }, "302": { "description": "Redirect to `redirect_uri` with `code` or `error`" }, "400": { "description": "Unknown or expired request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "No session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/oauth/device_authorization": { "post": { "tags": [ "identity" ], "summary": "Start the device flow.", "description": "Auth: public.", "operationId": "oauth_device_authorization", "requestBody": { "description": "`client_id=haarness-cli&scope=…`", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Device and user codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationResponse" } } } }, "400": { "description": "Unknown client or scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthErrorResponse" } } } } } } }, "/oauth/revoke": { "post": { "tags": [ "identity" ], "summary": "Revoke an access or refresh token (always `200`, §5.2).", "description": "Auth: public.", "operationId": "oauth_revoke", "requestBody": { "description": "`token=`", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Always, whether or not the token existed" } } } }, "/oauth/token": { "post": { "tags": [ "identity" ], "summary": "Exchange an authorization code, refresh token or device code for a token pair.", "description": "Auth: public. `Cache-Control: no-store`. A reused code or refresh token revokes the whole family.", "operationId": "oauth_token", "requestBody": { "description": "`grant_type` (`authorization_code` | `refresh_token` | `urn:ietf:params:oauth:grant-type:device_code`), `client_id`, and `code` + `redirect_uri` + `code_verifier` (optionally `device_label`, naming a phone's new sign-in in Settings → Devices, e.g. `Pixel 8 · Android 16`), `refresh_token` or `device_code`", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "The token pair", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "description": "`invalid_grant`, `authorization_pending`, `slow_down`, `access_denied`, `expired_token`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthErrorResponse" } } } }, "401": { "description": "`invalid_client`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthErrorResponse" } } } } } } }, "/openapi.json": { "get": { "tags": [ "meta" ], "summary": "This document.", "description": "Auth: public. The same bytes as the committed `docs/openapi.json`.", "operationId": "openapi_document", "responses": { "200": { "description": "The OpenAPI document", "content": { "application/json": {} } } } } }, "/readyz": { "get": { "tags": [ "meta" ], "summary": "Readiness: database, migrations and the per-service details of §3.2.5.", "description": "Auth: public. `503` carries the same body with `status = \"degraded\"`.", "operationId": "readyz", "responses": { "200": { "description": "Ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } }, "503": { "description": "Degraded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } } } } }, "/webhooks/stripe": { "post": { "tags": [ "billing" ], "summary": "Stripe events.", "description": "Auth: the `Stripe-Signature` header over the raw body. Records the event and enqueues `ProcessStripeEvent`\nin one transaction; a duplicate event id is acknowledged without enqueuing (§5.6).", "operationId": "stripe_webhook", "parameters": [ { "name": "Stripe-Signature", "in": "header", "description": "Stripe's `t=…,v1=…` signature over the raw body", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The raw Stripe event body (signature is checked over these bytes)", "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Recorded, and enqueued unless the event id was already stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeWebhookAck" } } } }, "400": { "description": "`invalid_request`: bad or missing signature; the body is logged as a SHA-256 hash only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "schemas": { "AcceptInvitationRequest": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "AccountApiKeyDto": { "type": "object", "required": [ "id", "accountId", "label", "prefix", "scopes", "createdAt", "policy" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null only for legacy keys without an expiry. New keys always expire." }, "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "policy": { "$ref": "#/components/schemas/KeyPolicyDto" }, "prefix": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "AccountDeletionPreviewDto": { "type": "object", "description": "`GET /api/v1/me/deletion`: what deleting the caller's account does, shown before they confirm. Deleted: the\nperson's sign-ins, devices, keys, computers, Cloud workspaces with their files, backups and exports, and the\npersonal account with any team nobody else belongs to. Kept: invoices, payments and the ledger, which the law\nrequires, and the audit trail.", "required": [ "confirmation", "mfaRequired", "workspaces", "subscriptionCancelled", "purchasedCredits", "teams", "allowed" ], "properties": { "allowed": { "type": "boolean", "description": "False while a team is `blocked`." }, "confirmation": { "type": "string", "description": "What to type to confirm: the account's email address, or `DELETE` for an account without one." }, "mfaRequired": { "type": "boolean", "description": "Whether a code from the authenticator app (or a recovery code) is required too." }, "purchasedCredits": { "$ref": "#/components/schemas/Amount", "description": "Purchased credits, forfeited with the account." }, "subscriptionCancelled": { "type": "boolean", "description": "Whether a paid plan is cancelled at once." }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/AccountDeletionTeamDto" } }, "workspaces": { "type": "integer", "format": "int32", "description": "Cloud workspaces destroyed with their files.", "minimum": 0 } } }, "AccountDeletionRequest": { "type": "object", "description": "`POST /api/v1/me/deletion`.", "required": [ "confirmation" ], "properties": { "code": { "type": [ "string", "null" ], "description": "Required when the preview says `mfaRequired`: an authenticator or recovery code." }, "confirmation": { "type": "string", "description": "The preview's `confirmation`, typed by the person (case and surrounding spaces do not matter)." } } }, "AccountDeletionResponse": { "type": "object", "required": [ "deletedAt" ], "properties": { "deletedAt": { "type": "string", "format": "date-time" } } }, "AccountDeletionTeamDto": { "type": "object", "required": [ "accountId", "name", "outcome" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "name": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/AccountDeletionTeamOutcome" } } }, "AccountDeletionTeamOutcome": { "type": "string", "description": "What becomes of a team when its member deletes their account.", "enum": [ "deleted", "left", "blocked" ] }, "AccountDto": { "type": "object", "required": [ "id", "kind", "slug", "name", "createdAt", "billingAccountId" ], "properties": { "billingAccountId": { "$ref": "#/components/schemas/BillingAccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/AccountId" }, "kind": { "$ref": "#/components/schemas/AccountKind" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "AccountId": { "type": "string" }, "AccountKind": { "type": "string", "enum": [ "personal", "organization" ] }, "AccountSummaryDto": { "type": "object", "required": [ "id", "kind", "slug", "name", "role" ], "properties": { "id": { "$ref": "#/components/schemas/AccountId" }, "kind": { "$ref": "#/components/schemas/AccountKind" }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/MembershipRole" }, "slug": { "type": "string", "description": "personal account slugs are always `u-` (§3.3.3)" } } }, "AddPasskeyRequest": { "type": "object", "description": "`POST /api/v1/me/sign-in-methods/passkeys`.", "required": [ "credential" ], "properties": { "credential": { "$ref": "#/components/schemas/PasskeyRegistrationDto" } } }, "AgentConfiguration": { "type": "object", "properties": { "agents": { "type": "object", "default": {}, "additionalProperties": { "$ref": "#/components/schemas/WorkspaceAgent" }, "propertyNames": { "type": "string" } }, "diskGb": { "type": "integer", "format": "int64", "default": 5 }, "idleTimeoutSecs": { "type": "integer", "format": "int64", "default": 600, "minimum": 0 }, "instructions": { "type": "string", "default": "" }, "knownHosts": { "type": "string", "description": "Pinned OpenSSH `known_hosts` entries for private Git and remote SSH hosts.", "default": "" }, "mcp": { "type": "object", "description": "Native MCP definitions. Secrets should use `${VARIABLE}` references to encrypted environment.", "default": {}, "additionalProperties": { "$ref": "#/components/schemas/McpConfiguration" }, "propertyNames": { "type": "string" } }, "model": { "type": [ "string", "null" ], "description": "Router model ID, e.g. `openai/gpt-5-nano`. None uses the live router default.", "default": null }, "permissions": { "description": "Native permission action or tool -> action/pattern map." }, "reasoningEffort": { "type": [ "string", "null" ], "default": null }, "region": { "type": [ "string", "null" ], "default": null }, "repository": { "oneOf": [ { "$ref": "#/components/schemas/WorkspaceTemplate" } ], "default": { "kind": "empty" } }, "resourceClass": { "oneOf": [ { "$ref": "#/components/schemas/ResourceClass" } ], "default": "shared-2cpu-4gb" }, "schemaVersion": { "type": "integer", "format": "int32", "default": 1, "minimum": 0 }, "skills": { "type": "object", "default": {}, "additionalProperties": { "$ref": "#/components/schemas/WorkspaceSkill" }, "propertyNames": { "type": "string" } }, "startupCommand": { "type": [ "string", "null" ], "default": null } }, "additionalProperties": false }, "AiOutputReason": { "type": "string", "description": "Why a reply is reported: the fixed list the apps offer.", "enum": [ "harmful", "hateful", "sexual", "malicious_code", "misleading", "other" ] }, "AiOutputReportDto": { "type": "object", "description": "`201` of `POST /api/v1/reports/ai-output`: the report was received.", "required": [ "id", "reason", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "reason": { "$ref": "#/components/schemas/AiOutputReason" } } }, "AiOutputReportOpsDto": { "type": "object", "description": "One report as operators review it. The reporter is named by user id only.", "required": [ "id", "reporterId", "accountId", "client", "source", "threadId", "excerpt", "excerptTruncated", "reason", "createdAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "client": { "type": "string", "description": "The app: a native sign-in's OAuth client id (`haarness-ios`, `haarness-android`, …), `web` or `api_key`." }, "createdAt": { "type": "string", "format": "date-time" }, "excerpt": { "type": "string" }, "excerptTruncated": { "type": "boolean" }, "hostId": { "type": [ "string", "null" ], "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "itemId": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "projectId": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ] }, "reason": { "$ref": "#/components/schemas/AiOutputReason" }, "remoteSessionId": { "type": [ "string", "null" ], "format": "uuid" }, "reporterId": { "$ref": "#/components/schemas/UserId" }, "resolution": { "type": [ "string", "null" ] }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "$ref": "#/components/schemas/AttentionSource" }, "threadId": { "type": "string" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid" } } }, "AiOutputReportRequest": { "type": "object", "description": "`POST /api/v1/reports/ai-output`: one reply of an agent, why it is reported, and where it is. The place takes the\nshape of a Live Activity's target: a computer's chat (`source` `host`, with `hostId` or the shared chat's\n`remoteSessionId`, and the runtime's `projectId`), or a Cloud workspace's (`source` `workspace`, `workspaceId`; `session` and `sessionId` from\napp builds made before the rename are read too).\nUnknown fields are ignored, so newer apps may send more.", "required": [ "reason", "source", "threadId", "excerpt" ], "properties": { "excerpt": { "type": "string", "description": "The reply's text as the app showed it: 1–8,000 characters (Unicode scalar values). Apps cut a longer reply\nthere and set `excerptTruncated`." }, "excerptTruncated": { "type": "boolean" }, "hostId": { "type": [ "string", "null" ], "format": "uuid" }, "itemId": { "type": [ "string", "null" ], "description": "The reply (runtime item id), 1–200 characters when given." }, "model": { "type": [ "string", "null" ], "description": "The model that wrote it, when the app knows: 1–200 characters." }, "note": { "type": [ "string", "null" ], "description": "What the person adds in their own words: 1–1,000 characters when given." }, "projectId": { "type": [ "string", "null" ], "description": "The runtime workspace on the computer." }, "provider": { "type": [ "string", "null" ], "description": "Its provider, when the app knows: 1–100 characters." }, "reason": { "$ref": "#/components/schemas/AiOutputReason" }, "remoteSessionId": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "$ref": "#/components/schemas/AttentionSource" }, "threadId": { "type": "string", "description": "The chat (runtime thread id), 1–200 characters." }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid" } } }, "AiOutputReportStatus": { "type": "string", "description": "Which reports `GET /internal/ops/reports/ai-output` lists.", "enum": [ "open", "resolved", "all" ] }, "AiOutputReportsOpsResponse": { "type": "object", "description": "`GET /internal/ops/reports/ai-output`: a page of reports, newest first, and how many wait for review.", "required": [ "items", "open" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AiOutputReportOpsDto" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" }, "open": { "type": "integer", "format": "int64", "description": "Open reports in all.", "minimum": 0 } } }, "AllowancePeriodId": { "type": "string" }, "Amount": { "type": "object", "description": "One amount in every unit a client may want to display.\nExample: `{\"nanos\":\"10000000000\",\"credits\":\"10000.000000\",\"usd\":\"10.000000000\"}`", "required": [ "nanos", "credits", "usd" ], "properties": { "credits": { "type": "string" }, "nanos": { "type": "string" }, "usd": { "type": "string" } } }, "AndroidAppLinkComponent": { "type": "object", "description": "One path pattern; `exclude` leaves matching links to the browser.", "required": [ "/" ], "properties": { "/": { "type": "string" }, "exclude": { "type": "boolean" } } }, "AndroidAppTarget": { "type": "object", "description": "The app: `namespace` `android_app`, its package and the SHA-256 fingerprints of the certificates that sign it\n(`AA:BB:…`, 32 colon-separated bytes in capitals).", "required": [ "namespace", "package_name", "sha256_cert_fingerprints" ], "properties": { "namespace": { "type": "string" }, "package_name": { "type": "string" }, "sha256_cert_fingerprints": { "type": "array", "items": { "type": "string" } } } }, "AndroidAssetLinkStatement": { "type": "object", "description": "One statement of `/.well-known/assetlinks.json` (the file is a JSON array of them): one Android app, by package and\nsigning certificates, may open this site's links — on Android 15+ only the paths of `relation_extensions`.", "required": [ "relation", "relation_extensions", "target" ], "properties": { "relation": { "type": "array", "items": { "type": "string" }, "description": "`[\"delegate_permission/common.handle_all_urls\"]`." }, "relation_extensions": { "$ref": "#/components/schemas/AndroidRelationExtensions" }, "target": { "$ref": "#/components/schemas/AndroidAppTarget" } } }, "AndroidHandleAllUrls": { "type": "object", "required": [ "dynamic_app_link_components" ], "properties": { "dynamic_app_link_components": { "type": "array", "items": { "$ref": "#/components/schemas/AndroidAppLinkComponent" } } } }, "AndroidRelationExtensions": { "type": "object", "description": "Android 15+ dynamic app links: the paths `handle_all_urls` covers.", "required": [ "delegate_permission/common.handle_all_urls" ], "properties": { "delegate_permission/common.handle_all_urls": { "$ref": "#/components/schemas/AndroidHandleAllUrls" } } }, "ApiKeyContextDto": { "type": "object", "required": [ "key", "accountName", "routerUrl" ], "properties": { "accountName": { "type": "string" }, "key": { "$ref": "#/components/schemas/AccountApiKeyDto" }, "routerUrl": { "type": "string" } } }, "AppleAppLinkComponent": { "type": "object", "description": "One path pattern; `exclude` leaves matching links to the browser.", "required": [ "/" ], "properties": { "/": { "type": "string" }, "exclude": { "type": "boolean" } } }, "AppleAppLinks": { "type": "object", "description": "Universal Links: which apps open which paths.", "required": [ "details" ], "properties": { "details": { "type": "array", "items": { "$ref": "#/components/schemas/AppleAppLinksDetail" } } } }, "AppleAppLinksDetail": { "type": "object", "required": [ "appIDs", "components" ], "properties": { "appIDs": { "type": "array", "items": { "type": "string" }, "description": "`.`, e.g. `ABCDE12345.dev.haarness.ios`." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/AppleAppLinkComponent" } } } }, "AppleAppSiteAssociation": { "type": "object", "description": "The whole association file.", "required": [ "applinks" ], "properties": { "applinks": { "$ref": "#/components/schemas/AppleAppLinks" } } }, "ApprovalMode": { "type": "string", "description": "The chat's approvals, set before the message is sent (`PUT /v1/threads/{id}/approval-mode`).", "enum": [ "auto", "review", "yolo" ] }, "ArtifactId": { "type": "string" }, "ArtifactRefDto": { "type": "object", "required": [ "id", "sha256", "sizeBytes", "contentType" ], "properties": { "contentType": { "type": "string" }, "id": { "$ref": "#/components/schemas/ArtifactId" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" } } }, "AttachResponse": { "type": "object", "description": "`{\"gatewayUrl\":\"http://127.0.0.1:18081/ws/0192…\",\"ticket\":\"hct_…\",\"expiresAt\":\"…\",\"cliCommand\":\"haarness attach http://127.0.0.1:18081/ws/0192… --token hct_…\",\"desktopUrl\":\"http://127.0.0.1:18081\",\"generationId\":\"…\"}`\n\n`cliCommand` carries the ticket in argv for copy-paste convenience (tickets are short-lived and revocable;\n`haarness attach` also reads `HAARNESS_SERVER_TOKEN`, which docs/API.md recommends for scripts). A ticket is\nbound to `generationId`: after a restart the gateway answers `400 remote_project \"workspace restarted; re-attach\"`\nand the client calls attach again (tickets are NOT revoked at stop).", "required": [ "gatewayUrl", "ticket", "expiresAt", "cliCommand", "desktopUrl", "generationId" ], "properties": { "cliCommand": { "type": "string" }, "desktopUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "gatewayUrl": { "type": "string" }, "generationId": { "$ref": "#/components/schemas/GenerationId" }, "ticket": { "type": "string" } } }, "AttentionItemDto": { "type": "object", "required": [ "id", "accountId", "source", "kind", "itemId", "threadId", "rootThreadId", "explicit", "actionable", "custom", "scheduled", "connected", "occurredAt", "observedAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "actionable": { "type": "boolean", "description": "`false` when Cloud cannot route an answer (an older daemon on the computer)." }, "category": { "type": [ "string", "null" ], "description": "Permissions: `bash`, `edit`, `read`, `external_directory`, `webfetch`, `browser`, `browser_site`, `mcp`, …" }, "chatTitle": { "type": [ "string", "null" ] }, "connected": { "type": "boolean", "description": "The computer is online or the workspace is running." }, "custom": { "type": "boolean", "description": "Questions: whether a typed answer is accepted." }, "explicit": { "type": "boolean", "description": "A Chrome site prompt: answer it in the chat on the computer running Chrome." }, "hostId": { "type": [ "string", "null" ], "format": "uuid", "description": "Computer items: the remote host." }, "hostName": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "description": "The runtime's permission or question id; the turn id of a finished chat." }, "kind": { "$ref": "#/components/schemas/AttentionKind" }, "observedAt": { "type": "string", "format": "date-time" }, "occurredAt": { "type": "string", "format": "date-time" }, "projectId": { "type": [ "string", "null" ], "description": "The computer's project (native workspace id), as in `/runtime/v1/host/workspaces/{projectId}`." }, "projectName": { "type": [ "string", "null" ] }, "remoteSessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "Items of a computer that shares single chats: the shared chat to open." }, "rootThreadId": { "type": "string", "format": "uuid", "description": "The chat to open." }, "scheduled": { "type": "boolean", "description": "The finished turn was started by a schedule." }, "source": { "$ref": "#/components/schemas/AttentionSource" }, "threadId": { "type": "string", "format": "uuid", "description": "The chat that asked: a sub-agent's chat when one asked." }, "turnId": { "type": [ "string", "null" ], "format": "uuid" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid", "description": "Cloud workspace items: the workspace." }, "workspaceTitle": { "type": [ "string", "null" ] } } }, "AttentionKind": { "type": "string", "enum": [ "permission", "question", "turn_completed", "turn_failed", "turn_stopped" ] }, "AttentionSource": { "type": "string", "description": "Where an item was observed: a connected computer (`remote_hosts`) or a Cloud workspace (`workspaces`).\n`session` is read as `workspace` for app builds made before the rename.", "enum": [ "host", "workspace" ] }, "AuthKind": { "type": "string", "enum": [ "session", "bearer" ] }, "AutoTopupDto": { "type": "object", "description": "The account's automatic top-up: when purchased credits fall below `threshold`, the saved card is charged\nthe `topupCode` pack (face value plus the service fee).", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "failedAt": { "type": [ "string", "null" ], "format": "date-time" }, "failure": { "type": [ "string", "null" ], "description": "Why the last automatic charge failed (automatic top-ups then turn off)." }, "threshold": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Amount" } ] }, "topupCode": { "type": [ "string", "null" ] } } }, "AutoTopupPolicyDto": { "type": "object", "description": "What an automatic top-up may be set to.", "required": [ "maxPerDay", "minThresholdCredits", "defaultThresholdCredits" ], "properties": { "defaultThresholdCredits": { "type": "integer", "format": "int64" }, "maxPerDay": { "type": "integer", "format": "int32", "minimum": 0 }, "minThresholdCredits": { "type": "integer", "format": "int64" } } }, "BillingAccountId": { "type": "string" }, "BillingInterval": { "type": "string", "description": "How often a subscription is billed. Allowances are granted monthly either way.", "enum": [ "month", "year" ] }, "BucketDto": { "type": "object", "required": [ "id", "kind", "unit", "available", "reserved", "consumed", "granted", "frozen" ], "properties": { "available": { "type": "string" }, "consumed": { "type": "string" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "frozen": { "type": "boolean" }, "granted": { "type": "string" }, "id": { "$ref": "#/components/schemas/BucketId" }, "kind": { "$ref": "#/components/schemas/BucketKind" }, "reserved": { "type": "string" }, "unit": { "$ref": "#/components/schemas/Unit" } } }, "BucketId": { "type": "string" }, "BucketKind": { "type": "string", "enum": [ "included_ai", "included_cloud", "included_egress", "purchased" ] }, "BudgetDto": { "type": "object", "required": [ "id", "scope", "limit", "spent", "periodStart", "periodEnd" ], "properties": { "id": { "$ref": "#/components/schemas/BudgetId" }, "limit": { "$ref": "#/components/schemas/Amount" }, "periodEnd": { "type": "string", "format": "date-time" }, "periodStart": { "type": "string", "format": "date-time" }, "scope": { "type": "string", "description": "account | project | key" }, "scopeId": { "type": [ "string", "null" ], "format": "uuid" }, "spent": { "$ref": "#/components/schemas/Amount" } } }, "BudgetId": { "type": "string" }, "Capabilities": { "type": "object", "required": [ "executable", "shell", "hooks", "mcp", "network", "secrets" ], "properties": { "executable": { "type": "boolean" }, "hooks": { "type": "array", "items": { "type": "string" } }, "mcp": { "type": "array", "items": { "type": "string" } }, "network": { "type": "boolean" }, "secrets": { "type": "array", "items": { "type": "string" } }, "shell": { "type": "boolean" } } }, "CapabilitiesResponse": { "type": "object", "description": "`GET /api/v1/capabilities` (§5.1 \"Versioning\").", "required": [ "apiVersion", "features" ], "properties": { "apiVersion": { "type": "string", "description": "`\"v1\"`" }, "features": { "type": "array", "items": { "type": "string" }, "description": "`[\"workspaces\",\"billing\",\"router_keys\",\"marketplace\",\"profiles\",\"device_flow\",\"native_pkce\"]`" } } }, "CheckoutRequest": { "oneOf": [ { "type": "object", "required": [ "planCode", "kind" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "interval": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingInterval", "description": "`month` (default) | `year`." } ] }, "kind": { "type": "string", "enum": [ "subscription" ] }, "planCode": { "$ref": "#/components/schemas/PlanCode" }, "seats": { "type": [ "integer", "null" ], "format": "int32", "description": "Seats of a per-seat plan (default: its minimum); ignored by single-person plans." } } }, { "type": "object", "required": [ "topupCode", "kind" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "kind": { "type": "string", "enum": [ "topup" ] }, "topupCode": { "type": "string" } } }, { "type": "object", "required": [ "kind" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "kind": { "type": "string", "enum": [ "trial" ] } } }, { "type": "object", "required": [ "kind" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "kind": { "type": "string", "enum": [ "payment_method" ] } } } ], "description": "`{\"kind\":\"subscription\",\"planCode\":\"pro\",\"interval\":\"year\"}` | `{\"kind\":\"subscription\",\"planCode\":\"team\",\"seats\":5}` |\n`{\"kind\":\"topup\",\"topupCode\":\"topup_20\"}` | `{\"kind\":\"trial\"}` (save a card, claim the trial) |\n`{\"kind\":\"payment_method\"}` (save a card for automatic top-ups)." }, "CheckoutResponse": { "type": "object", "required": [ "checkoutUrl", "paymentOperationId" ], "properties": { "checkoutUrl": { "type": "string" }, "paymentOperationId": { "$ref": "#/components/schemas/PaymentOperationId" } } }, "CloudAgentDto": { "type": "object", "required": [ "id", "accountId", "name", "description", "configuration", "version", "environmentNames", "createdAt", "updatedAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "configuration": { "$ref": "#/components/schemas/AgentConfiguration" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": "string" }, "environmentNames": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sshPublicKey": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64" } } }, "CloudClassDto": { "type": "object", "required": [ "id", "unitsPerHour", "cpus", "memoryMb", "cpuKind" ], "properties": { "cpuKind": { "type": "string" }, "cpus": { "type": "integer", "format": "int32", "minimum": 0 }, "id": { "type": "string" }, "memoryMb": { "type": "integer", "format": "int32", "minimum": 0 }, "unitsPerHour": { "type": "string" } } }, "CloudEntityEvent": { "oneOf": [ { "type": "object", "required": [ "scope", "resync", "entities", "type" ], "properties": { "entities": { "type": "array", "items": { "type": "string" } }, "resync": { "type": "boolean" }, "scope": { "type": "string" }, "type": { "type": "string", "enum": [ "ready" ] } } }, { "type": "object", "required": [ "accountId", "entity", "operation", "id", "type" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "entity": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "operation": { "type": "string" }, "revision": { "type": [ "integer", "null" ], "format": "int64" }, "type": { "type": "string", "enum": [ "entity.changed" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "resync_required" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "heartbeat" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "pong" ] } } } ] }, "CloudScheduleDto": { "type": "object", "required": [ "id", "accountId", "workspaceId", "chatId", "name", "prompt", "timezone", "nextRunAt", "enabled", "version", "createdAt", "updatedAt" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "chatId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "cron": { "type": [ "string", "null" ], "description": "Calendar cadence in `timezone`, when the schedule has one." }, "enabled": { "type": "boolean" }, "everySeconds": { "type": [ "integer", "null" ], "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "lastRun": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudScheduleRunDto", "description": "The most recent run, in lists and single reads." } ] }, "name": { "type": "string" }, "nextRunAt": { "type": "string", "format": "date-time" }, "prompt": { "type": "string" }, "timezone": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64" }, "workspaceId": { "type": "string", "format": "uuid" } } }, "CloudScheduleOccurrenceDto": { "type": "object", "required": [ "at", "shifted" ], "properties": { "at": { "type": "string", "format": "date-time" }, "shifted": { "type": "boolean", "description": "The rule's wall time did not exist that day (clocks went forward), so this run is at the end of the gap." } } }, "CloudSchedulePreviewDto": { "type": "object", "required": [ "timezone", "occurrences" ], "properties": { "occurrences": { "type": "array", "items": { "$ref": "#/components/schemas/CloudScheduleOccurrenceDto" } }, "timezone": { "type": "string" } } }, "CloudScheduleRunDto": { "type": "object", "required": [ "id", "scheduleId", "accountId", "workspaceId", "chatId", "scheduledAt", "status", "createdAt", "updatedAt" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "chatId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "scheduleId": { "type": "string", "format": "uuid" }, "scheduledAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "turnId": { "type": [ "string", "null" ], "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" }, "workspaceId": { "type": "string", "format": "uuid" } } }, "CloudScheduleTiming": { "type": "object", "description": "A replacement cadence for an existing schedule, validated like a create.", "properties": { "at": { "type": [ "string", "null" ], "format": "date-time" }, "cron": { "type": [ "string", "null" ] }, "everySeconds": { "type": [ "integer", "null" ], "format": "int64" }, "timezone": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CollectionDto": { "type": "object", "required": [ "id", "slug", "name", "description", "items" ], "properties": { "description": { "type": "string" }, "id": { "$ref": "#/components/schemas/CollectionId" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSummaryDto" } }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "CollectionId": { "type": "string" }, "CollectionRefDto": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "$ref": "#/components/schemas/CollectionId" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "CompatibilityDto": { "type": "object", "required": [ "platforms" ], "properties": { "maxRuntimeVersion": { "type": [ "string", "null" ] }, "minRuntimeVersion": { "type": [ "string", "null" ] }, "platforms": { "type": "array", "items": { "type": "string" } } } }, "ConnectSignInMethodRequest": { "type": "object", "description": "`POST /api/v1/me/sign-in-methods/connect`.", "required": [ "provider" ], "properties": { "loginHint": { "type": [ "string", "null" ], "description": "Passed to the provider as `login_hint` (Google preselects that account; the local fixture issuer picks its\ntest identity from it)." }, "provider": { "$ref": "#/components/schemas/SignInProvider", "description": "`google` or `apple`." } } }, "ConnectSignInMethodResponse": { "type": "object", "description": "Where the browser goes to connect the provider; the response also sets the login-state cookie.", "required": [ "redirectTo" ], "properties": { "redirectTo": { "type": "string" } } }, "ConsentDecisionRequest": { "type": "object", "required": [ "requestId", "decision" ], "properties": { "csrfToken": { "type": [ "string", "null" ], "description": "form posts carry the CSRF token here (§5.1); JSON clients use the header and leave it None" }, "decision": { "type": "string", "description": "approve | deny" }, "requestId": { "$ref": "#/components/schemas/OauthRequestId" } } }, "ConsentDecisionResponse": { "type": "object", "required": [ "redirectUri" ], "properties": { "redirectUri": { "type": "string", "description": "full redirect with code&state" } } }, "CreateAccountApiKeyRequest": { "type": "object", "required": [ "label", "scopes" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Defaults to 90 days; maximum 366 days." }, "label": { "type": "string" }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KeyPolicyDto" } ] }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Explicit Cloud and model capabilities. Unlisted operations are denied." } }, "additionalProperties": false }, "CreateAccountRequest": { "type": "object", "description": "`POST /api/v1/accounts`: a team account owned by the caller.", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateBudgetRequest": { "type": "object", "required": [ "scope", "limitCredits" ], "properties": { "limitCredits": { "type": "string" }, "periodEnd": { "type": [ "string", "null" ], "format": "date-time", "description": "default: start of the next UTC calendar month" }, "periodStart": { "type": [ "string", "null" ], "format": "date-time", "description": "default: start of the current UTC calendar month" }, "scope": { "type": "string", "description": "account (`scope_id` must be null) | project (a project of the account) | key (an `api_keys` row of the account)\n— 400 `validation_failed` otherwise" }, "scopeId": { "type": [ "string", "null" ], "format": "uuid" } } }, "CreateCloudAgentRequest": { "type": "object", "required": [ "name" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "configuration": { "$ref": "#/components/schemas/AgentConfiguration" }, "description": { "type": "string" }, "environment": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" } }, "additionalProperties": false }, "CreateCloudScheduleRequest": { "type": "object", "required": [ "workspaceId", "chatId", "name", "prompt" ], "properties": { "at": { "type": [ "string", "null" ], "format": "date-time", "description": "First run as RFC3339 with explicit offset. Required for a one-shot schedule; with `everySeconds` it is the\nfirst slot, with `cron` runs start at or after it." }, "chatId": { "type": "string", "format": "uuid" }, "cron": { "type": [ "string", "null" ], "description": "Calendar cadence: five-field cron (`minute hour day-of-month month day-of-week`, e.g. `0 9 * * 1-5`) read\nin `timezone`. Daylight saving keeps the wall time: a time skipped when clocks go forward runs at the end of\nthe gap, a time repeated when they go back runs once. Mutually exclusive with `everySeconds`." }, "everySeconds": { "type": [ "integer", "null" ], "format": "int64", "description": "Repeating cadence in seconds (60..31536000), elapsed time on a fixed grid. Missed ticks are coalesced; runs\nnever overlap." }, "name": { "type": "string" }, "prompt": { "type": "string" }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone (`Europe/Paris`) for `cron` and for display. Defaults to UTC." }, "workspaceId": { "type": "string", "format": "uuid", "description": "The workspace whose chat runs the prompt (`sessionId` is read too, from clients made before the rename)." } }, "additionalProperties": false }, "CreateInvitationRequest": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string" }, "role": { "$ref": "#/components/schemas/MembershipRole", "description": "admin | builder | viewer | billing (owners are never invited)." } } }, "CreateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateRouterKeyRequest": { "type": "object", "required": [ "label" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "label": { "type": "string" }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KeyPolicyDto" } ] } } }, "CreateRouterRequest": { "type": "object", "required": [ "name" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "credentialMode": { "type": "string" }, "description": { "type": "string" }, "modelAllowlist": { "type": [ "array", "null" ], "items": { "type": "string" } }, "name": { "type": "string" } }, "additionalProperties": false }, "CreateSubmissionRequest": { "type": "object", "required": [ "kind", "slug", "name", "summary", "visibility", "source" ], "properties": { "category": { "type": [ "string", "null" ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "kind": { "$ref": "#/components/schemas/ResourceKind" }, "licenseSpdx": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "source": { "$ref": "#/components/schemas/SubmissionSource" }, "summary": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/Visibility" } } }, "CreateWorkspaceRequest": { "type": "object", "description": "`POST /api/v1/workspaces`. Every field is optional: a blank workspace from the defaults, or one that starts from\na Cloud agent template (`cloudAgentId`), with `configuration` overriding the fields it supplies.", "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "cloudAgentId": { "type": [ "string", "null" ], "format": "uuid" }, "configuration": { "description": "Supplied top-level fields override the template/defaults. Maps replace as a whole." }, "diskGb": { "type": [ "integer", "null" ], "format": "int64", "description": "Deprecated: use `configuration.diskGb`.", "deprecated": true }, "environment": { "type": [ "object", "null" ], "description": "Write-only environment variables.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "initialPrompt": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InitialPromptRequest", "description": "A first message Cloud sends once the workspace is ready, into a new chat, so it reaches the agent even when\nthe person closes the tab or the app first. Requires the workspace to start (`start` not `false`). Check for\nthe `workspace_initial_prompt` capability first: an older Cloud refuses the field." } ] }, "name": { "type": [ "string", "null" ], "description": "Deprecated (the workspace API before templates): used as the title.", "deprecated": true }, "projectId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProjectId" } ] }, "region": { "type": [ "string", "null" ], "description": "Deprecated: use `configuration.region`.", "deprecated": true }, "resourceClass": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceClass", "description": "Deprecated: use `configuration.resourceClass`." } ] }, "start": { "type": [ "boolean", "null" ], "description": "Default true: provision, then start. `false` prepares it stopped." }, "startupCommand": { "type": [ "string", "null" ], "description": "Deprecated: use `configuration.startupCommand`.", "deprecated": true }, "template": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceTemplate", "description": "Deprecated: use `configuration.repository`." } ] }, "title": { "type": [ "string", "null" ], "description": "Defaults to the template's name, else \"New workspace\"." } }, "additionalProperties": false }, "CreatedAccountApiKeyResponse": { "type": "object", "required": [ "key", "routerUrl" ], "properties": { "key": { "$ref": "#/components/schemas/AccountApiKeyDto" }, "routerUrl": { "type": "string" }, "secretKey": { "type": [ "string", "null" ], "description": "Null on idempotency replay. Rotate if the one-time response was lost." } } }, "CreatedInvitationDto": { "type": "object", "description": "The invitation and the link it was emailed with (shown once, for sharing by hand).", "required": [ "invitation", "acceptUrl" ], "properties": { "acceptUrl": { "type": "string" }, "invitation": { "$ref": "#/components/schemas/InvitationDto" } } }, "CreatedRouterKeyResponse": { "type": "object", "required": [ "key", "routerUrl" ], "properties": { "key": { "$ref": "#/components/schemas/RouterKeyDto" }, "routerUrl": { "type": "string", "description": "`\"/v1\"`" }, "secretKey": { "type": [ "string", "null" ], "description": "full \"hcr__\", shown exactly once; `null` on an `Idempotency-Replayed` response because plaintext\nsecrets are never persisted (§5.1) — a client that lost the first response calls `rotate`" } } }, "CsrfResponse": { "type": "object", "required": [ "csrfToken" ], "properties": { "csrfToken": { "type": "string" } } }, "DeadJobDto": { "type": "object", "description": "The `JobRow`-like JSON of `GET /internal/ops/jobs/dead` and `POST /internal/ops/jobs/{id}/retry` (§4.9).", "required": [ "id", "kind", "payload", "status", "runAt", "attempts", "maxAttempts", "createdAt", "updatedAt" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "dedupeKey": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "lastError": { "type": [ "string", "null" ] }, "lockedBy": { "type": [ "string", "null" ] }, "lockedUntil": { "type": [ "string", "null" ], "format": "date-time" }, "maxAttempts": { "type": "integer", "format": "int32" }, "payload": {}, "runAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "queued|running|succeeded|failed|dead" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "DesiredState": { "type": "string", "enum": [ "running", "stopped", "deleted" ] }, "DeviceAuthorizationResponse": { "type": "object", "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ], "properties": { "device_code": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64", "description": "900", "minimum": 0 }, "interval": { "type": "integer", "format": "int64", "description": "5", "minimum": 0 }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" } } }, "DeviceCodeDetailsResponse": { "type": "object", "required": [ "userCode", "clientId", "clientName", "scopes", "expiresAt", "status" ], "properties": { "clientId": { "type": "string" }, "clientName": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "description": "pending | approved | denied | expired" }, "userCode": { "type": "string" } } }, "DeviceDecisionRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "description": "\"approve\" | \"deny\"" } } }, "DeviceDto": { "type": "object", "required": [ "id", "kind", "createdAt", "current" ], "properties": { "clientId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "current": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "kind": { "$ref": "#/components/schemas/DeviceKind", "description": "`browser_session` | `native_family`" }, "label": { "type": [ "string", "null" ] }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "DeviceKind": { "type": "string", "enum": [ "browser_session", "native_family" ] }, "DevicesResponse": { "type": "object", "required": [ "devices" ], "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceDto" } } } }, "DrainBucketRequest": { "type": "object", "required": [ "billingAccountId", "bucketKind" ], "properties": { "billingAccountId": { "$ref": "#/components/schemas/BillingAccountId" }, "bucketKind": { "$ref": "#/components/schemas/BucketKind" }, "leave": { "type": "string" } } }, "DrainBucketResponse": { "type": "object", "required": [ "bucket", "transactionId" ], "properties": { "bucket": { "$ref": "#/components/schemas/BucketDto" }, "transactionId": { "$ref": "#/components/schemas/TransactionId" } } }, "EmailAccountRequest": { "type": "object", "description": "Continue with email, or request a password reset. Both use non-enumerating responses.", "required": [ "email" ], "properties": { "displayName": { "type": "string", "description": "The name for an account the link creates; empty takes it from the address." }, "email": { "type": "string" }, "returnTo": { "type": [ "string", "null" ] } } }, "EmailConfirmRequest": { "type": "object", "description": "`POST /auth/email/confirm`: the emailed link's token, or its 6-digit code with the address it was sent to, in the\nbrowser that asked for it. Only the newest email's code for that address works there.", "properties": { "code": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "The address the code was sent to; required with `code`." }, "token": { "type": [ "string", "null" ] } } }, "EmailLinkRequest": { "type": "object", "description": "`POST /auth/email/link`: what an emailed sign-in link is for, without using it.", "required": [ "token" ], "properties": { "token": { "type": "string" } } }, "EmailLinkResponse": { "type": "object", "description": "The page that opens a link signs in at once in the browser that asked for it (`sameBrowser`); anywhere else it\nasks first, so a forwarded link or a mail scanner never signs anyone in.", "required": [ "email", "newAccount", "sameBrowser" ], "properties": { "email": { "type": "string" }, "newAccount": { "type": "boolean", "description": "The link creates the account." }, "sameBrowser": { "type": "boolean" } } }, "EmailLoginRequest": { "type": "object", "description": "Submitted only to the first-party sign-in page, never to an OAuth password grant.", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "returnTo": { "type": [ "string", "null" ] } } }, "EmailPasswordRequest": { "type": "object", "description": "One-use, expiring email action token plus the new password.", "required": [ "token", "password" ], "properties": { "password": { "type": "string" }, "token": { "type": "string" } } }, "EnqueueJobRequest": { "type": "object", "description": "`{\"job\":{\"kind\":\"meter_compute\",\"payload\":{}}}`", "required": [ "job" ], "properties": { "job": { "$ref": "#/components/schemas/JobKind" } } }, "EnqueueJobResponse": { "type": "object", "required": [ "jobId" ], "properties": { "jobId": { "$ref": "#/components/schemas/JobId" } } }, "EntitlementsDto": { "type": "object", "required": [ "aiCredits", "cloudUnits", "diskGb", "egressGb", "maxRunning" ], "properties": { "aiCredits": { "type": "integer", "format": "int64" }, "cloudUnits": { "type": "integer", "format": "int64" }, "diskGb": { "type": "integer", "format": "int64" }, "egressGb": { "type": "integer", "format": "int64" }, "maxRunning": { "type": "integer", "format": "int32" }, "periodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "periodStart": { "type": [ "string", "null" ], "format": "date-time" }, "planCode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanCode" } ] }, "planVersion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanVersionId" } ] }, "seats": { "type": "integer", "format": "int32", "description": "Seats the allowances above are pooled across (1 for single-person plans and the trial)." } } }, "EnvPlaceholderDto": { "type": "object", "required": [ "name", "description", "required" ], "properties": { "description": { "type": "string" }, "name": { "type": "string" }, "required": { "type": "boolean" } } }, "ErrorCode": { "type": "string", "enum": [ "invalid_request", "validation_failed", "invalid_cursor", "unsupported_media_type", "unauthenticated", "session_expired", "csrf_mismatch", "forbidden", "insufficient_scope", "account_suspended", "not_found", "conflict", "idempotency_mismatch", "invalid_state", "concurrency_limit", "push_platform_unavailable", "gone", "insufficient_credits", "budget_exceeded", "payment_required", "payload_too_large", "unprocessable", "rate_limited", "internal", "not_implemented", "provider_unavailable", "storage_unavailable", "bad_gateway", "remote_project" ] }, "ErrorEnvelope": { "type": "object", "description": "One envelope for every non-2xx response of cloud-api, cloud-gateway control routes and internal routes.\n(The managed router's /v1 uses the OpenAI-shaped `router_protocol::ErrorEnvelope`; the gateway's forwarded\nupstream errors are passed through byte-for-byte.)\n\nExample: `{\"code\":\"insufficient_credits\",\"message\":\"included AI credits exhausted and overage is not enabled\",\"requestId\":\"01J8…\",\"retryable\":false,\"details\":{\"unit\":\"nanos\",\"requested\":\"72000\",\"available\":\"0\"}}`", "required": [ "code", "message", "requestId", "retryable" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "details": {}, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" } } }, "ErrorEnvelopeLite": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } }, "ExportDownloadResponse": { "type": "object", "required": [ "url", "expiresAt", "sizeBytes", "sha256" ], "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" }, "url": { "type": "string" } } }, "ExtensionType": { "type": "string", "enum": [ "core", "tui", "freestyle" ] }, "GatewayServerInfo": { "type": "object", "description": "Synthetic /v1/info served by the gateway at the account origin (Desktop first contact).", "required": [ "name", "version", "schemaVersion", "serverInstanceId", "eventCursor", "capabilities" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" }, "description": "`[\"rest\",\"projects.v1\",\"workspaces.v1\"]`" }, "defaultModel": { "type": [ "string", "null" ] }, "defaultProvider": { "type": [ "string", "null" ] }, "eventCursor": { "type": "integer", "format": "int64", "description": "0", "minimum": 0 }, "gitBranch": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "\"haarness\"" }, "projectTrusted": { "type": [ "boolean", "null" ] }, "schemaVersion": { "type": "string", "description": "\"1\"" }, "serverInstanceId": { "type": "string", "format": "uuid" }, "version": { "type": "string" }, "workspace": { "type": [ "string", "null" ], "description": "\"Haarness Cloud\"" } } }, "GenerationDto": { "type": "object", "required": [ "id", "number", "status", "startedAt", "meteredUnitSeconds" ], "properties": { "id": { "$ref": "#/components/schemas/GenerationId" }, "meteredUnitSeconds": { "type": "integer", "format": "int64" }, "number": { "type": "integer", "format": "int32" }, "readyAt": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "starting | ready | stopping | stopped | failed" } } }, "GenerationId": { "type": "string" }, "GrantTestRequest": { "type": "object", "description": "`POST /internal/test/grant` → `billing::grant` with `GrantKey{source_kind: Test, source_ref: \"test:\",\nplan_version: current}` for a `period_days` period starting now.", "required": [ "billingAccountId", "planCode" ], "properties": { "billingAccountId": { "$ref": "#/components/schemas/BillingAccountId" }, "periodDays": { "type": "integer", "format": "int32", "description": "30", "minimum": 0 }, "planCode": { "$ref": "#/components/schemas/PlanCode" } } }, "GrantTestResponse": { "type": "object", "required": [ "periodId", "entitlements", "buckets", "replayed" ], "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/BucketDto" } }, "entitlements": { "$ref": "#/components/schemas/EntitlementsDto" }, "periodId": { "$ref": "#/components/schemas/AllowancePeriodId" }, "replayed": { "type": "boolean" }, "transactionId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TransactionId" } ] } } }, "HealthResponse": { "type": "object", "description": "`GET /healthz`.", "required": [ "status", "service", "version" ], "properties": { "service": { "type": "string" }, "status": { "type": "string", "description": "\"ok\"" }, "version": { "type": "string" } } }, "HostProjectInfo": { "type": "object", "required": [ "id", "name", "root", "git", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "git": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "root": { "type": "string" } } }, "HostProjectsResponse": { "type": "object", "required": [ "projects", "workspaces" ], "properties": { "currentWorkspaceId": { "type": [ "string", "null" ] }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/HostProjectInfo" } }, "workspaces": { "type": "array", "items": { "$ref": "#/components/schemas/HostWorkspaceInfo" } } } }, "HostWorkspaceInfo": { "type": "object", "required": [ "id", "projectId", "name", "path", "kind", "managed", "createdAt", "lastOpenedAt", "exists" ], "properties": { "baseCommit": { "type": [ "string", "null" ] }, "branch": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "exists": { "type": "boolean" }, "fromRef": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "type": "string", "description": "\"local\"" }, "lastOpenedAt": { "type": "string", "format": "date-time" }, "managed": { "type": "boolean" }, "name": { "type": "string" }, "path": { "type": "string" }, "projectId": { "type": "string" } } }, "InitialPromptRequest": { "type": "object", "description": "The first message of a new workspace (`initialPrompt`). Attachments are not carried: send those from the chat.", "required": [ "text" ], "properties": { "approvalMode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ApprovalMode", "description": "Set on the chat before the message is sent: `auto`, `review`, or `yolo` (every request approved without\nasking; a runtime without it starts the chat in Auto). Omitted, the chat starts in the runtime's default\nmode, which is Auto." } ] }, "chatTitle": { "type": [ "string", "null" ], "description": "1–200 characters on one line; omitted, the first 80 characters of the message on one line." }, "reasoningEffort": { "type": [ "string", "null" ], "description": "Reasoning effort for this message (`low`, `high`, …); omitted, the workspace's own applies." }, "text": { "type": "string", "description": "1–32768 bytes, not only whitespace." } }, "additionalProperties": false }, "InstallLockDto": { "type": "object", "required": [ "resourceId", "versionId" ], "properties": { "contentDigest": { "type": [ "string", "null" ] }, "resourceId": { "$ref": "#/components/schemas/ResourceId" }, "versionId": { "$ref": "#/components/schemas/VersionId" } } }, "InstallManifestDto": { "type": "object", "required": [ "manifestVersion", "resource", "version", "compatibility", "capabilities", "install", "lock" ], "properties": { "artifact": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SignedArtifactDto" } ] }, "capabilities": { "$ref": "#/components/schemas/Capabilities" }, "compatibility": { "$ref": "#/components/schemas/CompatibilityDto" }, "install": { "description": "exactly one key = kind; shapes in marketplace.md §7" }, "lock": { "$ref": "#/components/schemas/InstallLockDto" }, "manifestVersion": { "type": "integer", "format": "int32", "description": "1", "minimum": 0 }, "resource": { "$ref": "#/components/schemas/InstallManifestResource" }, "version": { "$ref": "#/components/schemas/InstallManifestVersion" } } }, "InstallManifestResource": { "type": "object", "required": [ "id", "kind", "slug", "publisher", "name" ], "properties": { "id": { "$ref": "#/components/schemas/ResourceId" }, "kind": { "$ref": "#/components/schemas/ResourceKind" }, "name": { "type": "string" }, "publisher": { "type": "string" }, "slug": { "type": "string" } } }, "InstallManifestVersion": { "type": "object", "required": [ "id", "number", "status", "yanked", "createdAt" ], "properties": { "contentDigest": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/VersionId" }, "number": { "type": "integer", "format": "int32" }, "semver": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ReviewStatus" }, "yanked": { "type": "boolean" } } }, "InvitationDto": { "type": "object", "description": "A pending invitation to a team account.", "required": [ "id", "email", "role", "createdAt", "expiresAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "email": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/InvitationId" }, "role": { "$ref": "#/components/schemas/MembershipRole" } } }, "InvitationId": { "type": "string" }, "Items_AccountApiKeyDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "label", "prefix", "scopes", "createdAt", "policy" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null only for legacy keys without an expiry. New keys always expire." }, "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "policy": { "$ref": "#/components/schemas/KeyPolicyDto" }, "prefix": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } }, "Items_AccountDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "slug", "name", "createdAt", "billingAccountId" ], "properties": { "billingAccountId": { "$ref": "#/components/schemas/BillingAccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/AccountId" }, "kind": { "$ref": "#/components/schemas/AccountKind" }, "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "Items_BudgetDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "scope", "limit", "spent", "periodStart", "periodEnd" ], "properties": { "id": { "$ref": "#/components/schemas/BudgetId" }, "limit": { "$ref": "#/components/schemas/Amount" }, "periodEnd": { "type": "string", "format": "date-time" }, "periodStart": { "type": "string", "format": "date-time" }, "scope": { "type": "string", "description": "account | project | key" }, "scopeId": { "type": [ "string", "null" ], "format": "uuid" }, "spent": { "$ref": "#/components/schemas/Amount" } } } } } }, "Items_DeadJobDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "The `JobRow`-like JSON of `GET /internal/ops/jobs/dead` and `POST /internal/ops/jobs/{id}/retry` (§4.9).", "required": [ "id", "kind", "payload", "status", "runAt", "attempts", "maxAttempts", "createdAt", "updatedAt" ], "properties": { "attempts": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "dedupeKey": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "lastError": { "type": [ "string", "null" ] }, "lockedBy": { "type": [ "string", "null" ] }, "lockedUntil": { "type": [ "string", "null" ], "format": "date-time" }, "maxAttempts": { "type": "integer", "format": "int32" }, "payload": {}, "runAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "queued|running|succeeded|failed|dead" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } }, "Items_InvitationDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "description": "A pending invitation to a team account.", "required": [ "id", "email", "role", "createdAt", "expiresAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "email": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/InvitationId" }, "role": { "$ref": "#/components/schemas/MembershipRole" } } } } } }, "Items_MemberDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "userId", "displayName", "role", "joinedAt" ], "properties": { "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "joinedAt": { "type": "string", "format": "date-time" }, "role": { "$ref": "#/components/schemas/MembershipRole" }, "userId": { "$ref": "#/components/schemas/UserId" } } } } } }, "Items_ProfileRecordDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "scope", "createdAt", "uploadedAt", "entryCount", "sizeBytes", "sha256" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "entryCount": { "type": "integer", "format": "int64" }, "id": { "$ref": "#/components/schemas/ProfileArchiveId" }, "name": { "type": "string" }, "scope": { "type": "string", "description": "global | local | both" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" }, "uploadedAt": { "type": "string", "format": "date-time" } } } } } }, "Items_ProjectDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "name", "createdAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/ProjectId" }, "name": { "type": "string" } } } } } }, "Items_RouterKeyDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "keyId", "prefix", "label", "scopeKind", "policy", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "keyId": { "$ref": "#/components/schemas/RouterKeyId" }, "label": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "policy": { "$ref": "#/components/schemas/KeyPolicyDto" }, "prefix": { "type": "string", "description": "\"hcr_\"" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scopeKind": { "type": "string", "description": "user | workspace" }, "workspaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceId" } ] } } } } } }, "Items_SnapshotDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "workspaceId", "kind", "status", "createdAt" ], "properties": { "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/SnapshotId" }, "kind": { "type": "string", "description": "provider | export" }, "sizeBytes": { "type": [ "integer", "null" ], "format": "int64" }, "status": { "type": "string" }, "workspaceId": { "$ref": "#/components/schemas/WorkspaceId" } } } } } }, "Items_VersionSummaryDto": { "type": "object", "description": "`{\"items\": [...]}`, the shape of the §5.3 list routes that are not cursor-paginated.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "number", "status", "yanked", "createdAt" ], "properties": { "contentDigest": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/VersionId" }, "number": { "type": "integer", "format": "int32" }, "semver": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ReviewStatus" }, "yanked": { "type": "boolean" } } } } } }, "JobId": { "type": "string" }, "JobKind": { "oneOf": [ { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "process_stripe_event" ] }, "payload": { "type": "object", "required": [ "event_id" ], "properties": { "event_id": { "type": "string" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "grant_allowances" ] }, "payload": { "type": "object", "required": [ "billing_account_id", "subscription_id", "invoice_id", "period_start", "period_end", "plan_version", "plan_code" ], "properties": { "billing_account_id": { "$ref": "#/components/schemas/BillingAccountId" }, "billing_interval": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingInterval", "description": "`year` grants only the first month of the invoice period; later months come from\n`annual_allowance_sweep`. Absent: `month`." } ] }, "invoice_id": { "type": "string" }, "period_end": { "type": "string", "format": "date-time" }, "period_start": { "type": "string", "format": "date-time" }, "plan_code": { "$ref": "#/components/schemas/PlanCode" }, "plan_version": { "$ref": "#/components/schemas/PlanVersionId" }, "seats": { "type": [ "integer", "null" ], "format": "int32", "description": "The invoiced quantity: seats of a per-seat plan (absent on jobs queued before seats existed: 1)." }, "subscription_id": { "$ref": "#/components/schemas/SubscriptionId" } } } } }, { "type": "object", "description": "Grants the next monthly allowance of every annual subscription whose current month has ended.", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "annual_allowance_sweep" ] }, "payload": { "type": "object", "description": "Grants the next monthly allowance of every annual subscription whose current month has ended." } } }, { "type": "object", "description": "Emails an account when an included allowance passes 80% or runs out (once per period and allowance).", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "allowance_alert_sweep" ] }, "payload": { "type": "object", "description": "Emails an account when an included allowance passes 80% or runs out (once per period and allowance)." } } }, { "type": "object", "description": "Charges the saved card of every account with automatic top-ups on whose purchased credits are below\nits threshold.", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "auto_topup_sweep" ] }, "payload": { "type": "object", "description": "Charges the saved card of every account with automatic top-ups on whose purchased credits are below\nits threshold." } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "expire_allowance_periods" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "expire_reservations" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "reconcile_unresolved_reservations" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_provision" ] }, "payload": { "type": "object", "required": [ "workspace_id", "operation_id" ], "properties": { "operation_id": { "$ref": "#/components/schemas/OperationId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_start" ] }, "payload": { "type": "object", "required": [ "workspace_id", "operation_id" ], "properties": { "operation_id": { "$ref": "#/components/schemas/OperationId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_stop" ] }, "payload": { "type": "object", "required": [ "workspace_id", "operation_id", "reason", "grace_secs" ], "properties": { "grace_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "operation_id": { "$ref": "#/components/schemas/OperationId", "description": "always an operation row, also for idle/exhaustion/reconcile stops" }, "reason": { "$ref": "#/components/schemas/StopReason" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_delete" ] }, "payload": { "type": "object", "required": [ "workspace_id", "operation_id" ], "properties": { "operation_id": { "$ref": "#/components/schemas/OperationId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_export" ] }, "payload": { "type": "object", "required": [ "workspace_id", "operation_id" ], "properties": { "operation_id": { "$ref": "#/components/schemas/OperationId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_snapshot" ] }, "payload": { "type": "object", "required": [ "workspace_id", "operation_id" ], "properties": { "operation_id": { "$ref": "#/components/schemas/OperationId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_restore" ] }, "payload": { "type": "object", "required": [ "workspace_id", "operation_id", "snapshot_id" ], "properties": { "operation_id": { "$ref": "#/components/schemas/OperationId" }, "snapshot_id": { "$ref": "#/components/schemas/SnapshotId" }, "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "reconcile_workspaces" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "meter_compute" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "meter_storage" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "idle_sweep" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "cloud_schedule_sweep" ] }, "payload": { "type": "object" } } }, { "type": "object", "description": "Delivers each new Cloud workspace's first message (`initialPrompt`) once its runtime is ready, then follows that\nturn until it ends.", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_launch_sweep" ] }, "payload": { "type": "object", "description": "Delivers each new Cloud workspace's first message (`initialPrompt`) once its runtime is ready, then follows that\nturn until it ends." } } }, { "type": "object", "description": "Reads what each running Cloud workspace waits on (pending permissions and questions) and which of its root\nchats finished, straight from the runtime; never feeds an idle-stop decision.", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "workspace_attention_sweep" ] }, "payload": { "type": "object", "description": "Reads what each running Cloud workspace waits on (pending permissions and questions) and which of its root\nchats finished, straight from the runtime; never feeds an idle-stop decision." } } }, { "type": "object", "description": "Turns what waits on a person, and chats that finished, into push notifications and Live Activity updates on\ntheir phones, from the attention rows' transitions (never once per sweep).", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "push_dispatch" ] }, "payload": { "type": "object", "description": "Turns what waits on a person, and chats that finished, into push notifications and Live Activity updates on\ntheir phones, from the attention rows' transitions (never once per sweep)." } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "expire_attach_tickets" ] }, "payload": { "type": "object" } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "deletion_grace_sweep" ] }, "payload": { "type": "object" } } }, { "type": "object", "description": "Deletes usage statistics days older than 400 days and the installations not seen for that long.", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "usage_statistics_sweep" ] }, "payload": { "type": "object", "description": "Deletes usage statistics days older than 400 days and the installations not seen for that long." } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "backup_workspace" ] }, "payload": { "type": "object", "required": [ "workspace_id" ], "properties": { "workspace_id": { "$ref": "#/components/schemas/WorkspaceId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "validate_submission" ] }, "payload": { "type": "object", "required": [ "submission_id" ], "properties": { "submission_id": { "$ref": "#/components/schemas/SubmissionId" } } } } }, { "type": "object", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "send_notification" ] }, "payload": { "type": "object", "required": [ "notification_id" ], "properties": { "notification_id": { "$ref": "#/components/schemas/NotificationId" } } } } }, { "type": "object", "description": "Sends one `push` delivery to a phone (`notification_deliveries.channel = 'push'`). Pushes have their own kind\nso a worker from before pushes, which claims `send_notification` and treats every delivery as an email,\nnever claims one (during a rolling deploy or after a rollback): it waits for a worker that knows it.", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "send_push" ] }, "payload": { "type": "object", "description": "Sends one `push` delivery to a phone (`notification_deliveries.channel = 'push'`). Pushes have their own kind\nso a worker from before pushes, which claims `send_notification` and treats every delivery as an email,\nnever claims one (during a rolling deploy or after a rollback): it waits for a worker that knows it.", "required": [ "notification_id" ], "properties": { "notification_id": { "$ref": "#/components/schemas/NotificationId" } } } } }, { "type": "object", "description": "What a deleted account still has outside the database, and what it still holds in it: it cancels the\naccount's Stripe subscription at once, waits for its Cloud workspaces to be destroyed, then deletes their backups\nand exports and the account's profile archives from object storage and erases its workspaces' records, Cloud\nagents, schedules, projects, routers and marketplace listings, keeping only nameless rows the ledger names\n(queued by `cloud_store::account_deletion::execute`).", "required": [ "payload", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "account_purge" ] }, "payload": { "type": "object", "description": "What a deleted account still has outside the database, and what it still holds in it: it cancels the\naccount's Stripe subscription at once, waits for its Cloud workspaces to be destroyed, then deletes their backups\nand exports and the account's profile archives from object storage and erases its workspaces' records, Cloud\nagents, schedules, projects, routers and marketplace listings, keeping only nameless rows the ledger names\n(queued by `cloud_store::account_deletion::execute`).", "required": [ "account_id" ], "properties": { "account_id": { "$ref": "#/components/schemas/AccountId" } } } } } ], "description": "Payload = JSON of the variant content: `{\"kind\":\"meter_compute\",\"payload\":{}}`." }, "KeyPolicyDto": { "type": "object", "properties": { "maxConcurrency": { "type": "integer", "format": "int32", "minimum": 0 }, "modelAllowlist": { "type": [ "array", "null" ], "items": { "type": "string" } }, "monthlyBudgetCredits": { "type": [ "string", "null" ] }, "perRequestMaxCredits": { "type": [ "string", "null" ] }, "ratePerMinute": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "LaunchStatus": { "type": "string", "description": "Where a launch stands: the schedule-run vocabulary.", "enum": [ "pending", "running", "needs_attention", "completed", "failed", "interrupted", "cancelled" ] }, "LedgerCheckResponse": { "type": "object", "required": [ "billingAccountId", "mismatches" ], "properties": { "billingAccountId": { "$ref": "#/components/schemas/BillingAccountId" }, "mismatches": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerMismatchDto" } } } }, "LedgerEntryDto": { "type": "object", "required": [ "transactionId", "kind", "account", "unit", "amount", "createdAt", "reference" ], "properties": { "account": { "type": "string" }, "amount": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "kind": { "$ref": "#/components/schemas/LedgerTransactionKind" }, "reference": {}, "transactionId": { "$ref": "#/components/schemas/TransactionId" }, "unit": { "$ref": "#/components/schemas/Unit" } } }, "LedgerMismatchDto": { "type": "object", "required": [ "bucketId", "ledgerBalance", "bucketBalance" ], "properties": { "bucketBalance": { "type": "string" }, "bucketId": { "$ref": "#/components/schemas/BucketId" }, "ledgerBalance": { "type": "string" } } }, "LedgerTransactionKind": { "type": "string", "enum": [ "grant", "purchase", "settle", "expire", "refund", "adjustment" ] }, "LiveActivityDto": { "type": "object", "required": [ "id", "platform", "environment", "bundleId", "target", "threadId", "createdAt", "updatedAt" ], "properties": { "bundleId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "environment": { "$ref": "#/components/schemas/PushEnvironment" }, "id": { "type": "string", "format": "uuid" }, "platform": { "$ref": "#/components/schemas/PushPlatform" }, "target": { "$ref": "#/components/schemas/LiveActivityTargetDto" }, "threadId": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "LiveActivityTargetDto": { "type": "object", "description": "The chat a Live Activity follows: `source: host` with `hostId` (and `projectId`), or `remoteSessionId` for a\nshared chat; `source: workspace` with `workspaceId` (`session`/`sessionId` from app builds made before the\nrename are read too).", "required": [ "source" ], "properties": { "hostId": { "type": [ "string", "null" ], "format": "uuid" }, "projectId": { "type": [ "string", "null" ] }, "remoteSessionId": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "$ref": "#/components/schemas/AttentionSource" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid" } } }, "McpConfiguration": { "type": "object", "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "type": [ "string", "null" ] }, "cwd": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "environment": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "oauth": { "type": [ "boolean", "null" ] }, "oauthClientId": { "type": [ "string", "null" ] }, "oauthScopes": { "type": "array", "items": { "type": "string" } }, "timeoutMs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "url": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "MeResponse": { "type": "object", "description": "`GET /api/v1/me`.", "required": [ "user", "accounts", "defaultAccountId", "authKind", "scopes" ], "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSummaryDto" } }, "authKind": { "$ref": "#/components/schemas/AuthKind" }, "defaultAccountId": { "$ref": "#/components/schemas/AccountId" }, "scopes": { "type": "array", "items": { "type": "string" } }, "session": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SessionSummaryDto" } ] }, "user": { "$ref": "#/components/schemas/UserDto" } } }, "MemberDto": { "type": "object", "required": [ "userId", "displayName", "role", "joinedAt" ], "properties": { "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "joinedAt": { "type": "string", "format": "date-time" }, "role": { "$ref": "#/components/schemas/MembershipRole" }, "userId": { "$ref": "#/components/schemas/UserId" } } }, "MembershipRole": { "type": "string", "enum": [ "owner", "admin", "builder", "viewer", "billing" ] }, "MfaChallengeDto": { "type": "object", "description": "`GET /auth/mfa`: the sign-in waiting for its code in this browser.", "required": [ "method", "expiresAt" ], "properties": { "email": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "method": { "$ref": "#/components/schemas/MfaMethod" } } }, "MfaCodeRequest": { "type": "object", "description": "A code from the authenticator app (`123456`) or an unused recovery code (`xxxxx-xxxxx`).", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "MfaConfirmResponse": { "type": "object", "description": "`POST /api/v1/mfa/totp/confirm`. Recovery codes are issued when two-factor authentication turns on and are\nkept when an authenticator is replaced.", "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" } } } }, "MfaMethod": { "type": "string", "description": "How the first factor of a waiting sign-in was proven.", "enum": [ "google", "password", "email", "apple", "passkey" ] }, "MfaRecoveryCodesResponse": { "type": "object", "description": "One-use recovery codes. Shown once; only their hashes are stored.", "required": [ "recoveryCodes" ], "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" } } } }, "MfaSetupRequest": { "type": "object", "description": "Start authenticator setup. Replacing an enabled authenticator requires a current code.", "properties": { "code": { "type": [ "string", "null" ] } } }, "MfaSetupResponse": { "type": "object", "description": "The new secret, for the QR code and for manual entry. Shown once; confirm it before `expiresAt`.", "required": [ "secret", "otpauthUri", "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "otpauthUri": { "type": "string" }, "secret": { "type": "string", "description": "Base32, the form authenticator apps accept when typed." } } }, "MfaStatusDto": { "type": "object", "description": "`GET /api/v1/mfa`: the caller's two-factor authentication (ADR-0013).", "required": [ "available", "enabled", "recoveryCodesRemaining", "trustedBrowsers", "thisBrowserTrusted" ], "properties": { "available": { "type": "boolean", "description": "`false` when this deployment cannot store authenticator secrets." }, "enabled": { "type": "boolean" }, "enabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "recoveryCodesRemaining": { "type": "integer", "format": "int32", "minimum": 0 }, "thisBrowserTrusted": { "type": "boolean" }, "trustedBrowsers": { "type": "integer", "format": "int32", "description": "Browsers that skip the code until their trust expires.", "minimum": 0 } } }, "MfaVerifyRequest": { "type": "object", "description": "The second step of a browser sign-in.", "required": [ "code" ], "properties": { "code": { "type": "string" }, "trustBrowser": { "type": "boolean", "description": "Skip the code in this browser for 30 days." } } }, "ModelPriceDto": { "type": "object", "required": [ "modelId", "provider", "inputPerMillionUsd", "outputPerMillionUsd", "priceSource", "inputCreditsPerMillion", "outputCreditsPerMillion", "status" ], "properties": { "cacheReadPerMillionUsd": { "type": [ "string", "null" ] }, "cacheWritePerMillionUsd": { "type": [ "string", "null" ], "description": "The five-minute cache-write rate, where the model has one." }, "contextLength": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "inputCreditsPerMillion": { "type": "string" }, "inputPerMillionUsd": { "type": "string" }, "maxOutputTokens": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "modelId": { "type": "string" }, "outputCreditsPerMillion": { "type": "string" }, "outputPerMillionUsd": { "type": "string" }, "priceCheckedOn": { "type": [ "string", "null" ], "description": "For `haarness` rates, the day they were checked against the provider's page (`YYYY-MM-DD`)." }, "priceSource": { "type": "string", "description": "Where these rates come from: `haarness` (reviewed against the provider's price page), `openrouter`\n(models the reviewed table does not list), or `fixture` in tests." }, "provider": { "type": "string" }, "status": { "$ref": "#/components/schemas/TariffStatus" } } }, "ModelPricesResponse": { "type": "object", "required": [ "pricebookVersion", "publishedAt", "models" ], "properties": { "defaultModel": { "type": [ "string", "null" ], "description": "The model Cloud workspaces start on, when it is configured and active in this pricebook (`provider/model`)." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelPriceDto" } }, "pricebookVersion": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" } } }, "NativeRouterSessionRequest": { "type": "object", "description": "Short-lived router access tied to the native OAuth refresh family.", "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "routerId": { "type": [ "string", "null" ], "format": "uuid" } } }, "NativeRouterSessionResponse": { "type": "object", "required": [ "token", "routerUrl", "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time" }, "routerUrl": { "type": "string" }, "token": { "type": "string" } } }, "NotificationId": { "type": "string" }, "OauthErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "`invalid_request` | `invalid_grant` | `invalid_client` | `unauthorized_client` | `unsupported_grant_type` |\n`authorization_pending` | `slow_down` | `expired_token` | `access_denied`" }, "error_description": { "type": [ "string", "null" ] } } }, "OauthRequestId": { "type": "string" }, "OperationDto": { "type": "object", "required": [ "id", "accountId", "kind", "status", "request", "createdAt", "lastSequence" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ErrorEnvelopeLite" } ] }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/OperationId" }, "kind": { "type": "string", "description": "create | start | stop | delete | export | snapshot | restore" }, "lastSequence": { "type": "integer", "format": "int64" }, "request": { "description": "e.g. `{\"reason\":\"idle\",\"graceSecs\":10}` on worker-initiated stops" }, "result": {}, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/OperationStatus" }, "workspaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceId" } ] } } }, "OperationEventDto": { "type": "object", "required": [ "sequence", "kind", "message", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "details": {}, "kind": { "type": "string", "description": "queued | started | progress | provider | succeeded | failed" }, "message": { "type": "string" }, "sequence": { "type": "integer", "format": "int64" } } }, "OperationEventsResponse": { "type": "object", "required": [ "operation", "events", "nextAfter" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/OperationEventDto" } }, "nextAfter": { "type": "integer", "format": "int64" }, "operation": { "$ref": "#/components/schemas/OperationDto" } } }, "OperationId": { "type": "string" }, "OperationStatus": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "cancelled" ] }, "OverageDto": { "type": "object", "required": [ "baseCloudCreditsPerHour", "diskCreditsPerGbMonth", "egressCreditsPerGb" ], "properties": { "baseCloudCreditsPerHour": { "type": "string" }, "diskCreditsPerGbMonth": { "type": "string" }, "egressCreditsPerGb": { "type": "string" } } }, "PageQuery": { "type": "object", "description": "Query `cursor` (opaque) + `limit` (1..=200, default 50).", "properties": { "cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer", "format": "int32", "description": "1..=200, default 50", "minimum": 0 } } }, "Page_AttentionItemDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "source", "kind", "itemId", "threadId", "rootThreadId", "explicit", "actionable", "custom", "scheduled", "connected", "occurredAt", "observedAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "actionable": { "type": "boolean", "description": "`false` when Cloud cannot route an answer (an older daemon on the computer)." }, "category": { "type": [ "string", "null" ], "description": "Permissions: `bash`, `edit`, `read`, `external_directory`, `webfetch`, `browser`, `browser_site`, `mcp`, …" }, "chatTitle": { "type": [ "string", "null" ] }, "connected": { "type": "boolean", "description": "The computer is online or the workspace is running." }, "custom": { "type": "boolean", "description": "Questions: whether a typed answer is accepted." }, "explicit": { "type": "boolean", "description": "A Chrome site prompt: answer it in the chat on the computer running Chrome." }, "hostId": { "type": [ "string", "null" ], "format": "uuid", "description": "Computer items: the remote host." }, "hostName": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "description": "The runtime's permission or question id; the turn id of a finished chat." }, "kind": { "$ref": "#/components/schemas/AttentionKind" }, "observedAt": { "type": "string", "format": "date-time" }, "occurredAt": { "type": "string", "format": "date-time" }, "projectId": { "type": [ "string", "null" ], "description": "The computer's project (native workspace id), as in `/runtime/v1/host/workspaces/{projectId}`." }, "projectName": { "type": [ "string", "null" ] }, "remoteSessionId": { "type": [ "string", "null" ], "format": "uuid", "description": "Items of a computer that shares single chats: the shared chat to open." }, "rootThreadId": { "type": "string", "format": "uuid", "description": "The chat to open." }, "scheduled": { "type": "boolean", "description": "The finished turn was started by a schedule." }, "source": { "$ref": "#/components/schemas/AttentionSource" }, "threadId": { "type": "string", "format": "uuid", "description": "The chat that asked: a sub-agent's chat when one asked." }, "turnId": { "type": [ "string", "null" ], "format": "uuid" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid", "description": "Cloud workspace items: the workspace." }, "workspaceTitle": { "type": [ "string", "null" ] } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_CloudAgentDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "name", "description", "configuration", "version", "environmentNames", "createdAt", "updatedAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "configuration": { "$ref": "#/components/schemas/AgentConfiguration" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": "string" }, "environmentNames": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sshPublicKey": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_CloudScheduleDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "workspaceId", "chatId", "name", "prompt", "timezone", "nextRunAt", "enabled", "version", "createdAt", "updatedAt" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "chatId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "cron": { "type": [ "string", "null" ], "description": "Calendar cadence in `timezone`, when the schedule has one." }, "enabled": { "type": "boolean" }, "everySeconds": { "type": [ "integer", "null" ], "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "lastRun": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudScheduleRunDto", "description": "The most recent run, in lists and single reads." } ] }, "name": { "type": "string" }, "nextRunAt": { "type": "string", "format": "date-time" }, "prompt": { "type": "string" }, "timezone": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64" }, "workspaceId": { "type": "string", "format": "uuid" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_CloudScheduleRunDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "scheduleId", "accountId", "workspaceId", "chatId", "scheduledAt", "status", "createdAt", "updatedAt" ], "properties": { "accountId": { "type": "string", "format": "uuid" }, "chatId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "scheduleId": { "type": "string", "format": "uuid" }, "scheduledAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "turnId": { "type": [ "string", "null" ], "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" }, "workspaceId": { "type": "string", "format": "uuid" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_CollectionRefDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "name" ], "properties": { "id": { "$ref": "#/components/schemas/CollectionId" }, "name": { "type": "string" }, "slug": { "type": "string" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_LedgerEntryDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "transactionId", "kind", "account", "unit", "amount", "createdAt", "reference" ], "properties": { "account": { "type": "string" }, "amount": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "kind": { "$ref": "#/components/schemas/LedgerTransactionKind" }, "reference": {}, "transactionId": { "$ref": "#/components/schemas/TransactionId" }, "unit": { "$ref": "#/components/schemas/Unit" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_OperationDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "kind", "status", "request", "createdAt", "lastSequence" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ErrorEnvelopeLite" } ] }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/OperationId" }, "kind": { "type": "string", "description": "create | start | stop | delete | export | snapshot | restore" }, "lastSequence": { "type": "integer", "format": "int64" }, "request": { "description": "e.g. `{\"reason\":\"idle\",\"graceSecs\":10}` on worker-initiated stops" }, "result": {}, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/OperationStatus" }, "workspaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceId" } ] } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_PaymentDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "amountCents", "currency", "face", "paidAt" ], "properties": { "amountCents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "face": { "$ref": "#/components/schemas/Amount" }, "id": { "$ref": "#/components/schemas/PaymentId" }, "kind": { "type": "string", "description": "subscription | topup | `auto_topup`" }, "paidAt": { "type": "string", "format": "date-time" }, "stripeCheckoutSessionId": { "type": [ "string", "null" ] }, "stripeInvoiceId": { "type": [ "string", "null" ] } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_RemoteHostDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "name", "mode", "connected", "metadata", "createdAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "connected": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": {}, "mode": { "type": "string", "description": "`host` exposes projects; `sessions` exposes only explicitly published chats." }, "name": { "type": "string" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_RemoteSessionDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "hostId", "accountId", "projectId", "threadId", "title", "connected", "createdAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "connected": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "hostId": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string" }, "threadId": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_ResourceSummaryDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "slug", "publisher", "name", "summary", "keywords", "visibility", "updatedAt" ], "properties": { "category": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/ResourceId" }, "keywords": { "type": "array", "items": { "type": "string" } }, "kind": { "$ref": "#/components/schemas/ResourceKind" }, "latestVersion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VersionSummaryDto" } ] }, "name": { "type": "string" }, "publisher": { "$ref": "#/components/schemas/PublisherRefDto" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "visibility": { "$ref": "#/components/schemas/Visibility" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_UsageItemDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "kind", "id", "occurredAt", "quantities", "amount", "bucketKinds", "settlementRef" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "bucketKinds": { "type": "array", "items": { "$ref": "#/components/schemas/BucketKind" } }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "`ai_request` | compute | storage | egress" }, "model": { "type": [ "string", "null" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "provider": { "type": [ "string", "null" ] }, "quantities": { "description": "`{\"uncachedInputTokens\":..,\"cachedInputTokens\":..,\"cacheWriteTokens\":..,\"outputTokens\":..}` | `{\"unitSeconds\":..,\"multiplier\":..}`" }, "requestId": { "type": [ "string", "null" ] }, "settlementRef": { "type": "string", "description": "The idempotency key the item settled under: `usage_settlements.settlement_id` for `ai_request`,\n`.settlement_ref` for the compute/storage/egress intervals. A compute interval written by the\nstop path is `compute::final` (§7 row 8), which is the only way to observe the final\nsettlement over HTTP." }, "workspaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceId" } ] } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Page_WorkspaceDto": { "type": "object", "description": "`{items, nextCursor}`.", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "accountId", "title", "name", "configuration", "version", "environmentNames", "region", "resourceClass", "diskGb", "imageRef", "desiredState", "observedState", "idleTimeoutSecs", "createdAt", "updatedAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "agentSnapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudAgentDto", "description": "That template as it was when the workspace was created (immutable provenance)." } ] }, "cloudAgentId": { "type": [ "string", "null" ], "format": "uuid", "description": "The Cloud agent template the workspace started from, if any." }, "configuration": { "$ref": "#/components/schemas/AgentConfiguration" }, "createdAt": { "type": "string", "format": "date-time" }, "desiredState": { "$ref": "#/components/schemas/DesiredState" }, "diskGb": { "type": "integer", "format": "int64" }, "environmentNames": { "type": "array", "items": { "type": "string" } }, "failureReason": { "type": [ "string", "null" ] }, "generation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GenerationDto" } ] }, "id": { "$ref": "#/components/schemas/WorkspaceId" }, "idleTimeoutSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "imageRef": { "type": "string" }, "keepAliveUntil": { "type": [ "string", "null" ], "format": "date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "format": "date-time" }, "launch": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceLaunchDto", "description": "How Cloud is delivering the workspace's first message; absent on workspaces created without one." } ] }, "name": { "type": "string", "description": "The machine's slug. Kept for clients made before titles; show `title` instead.", "deprecated": true }, "observedState": { "$ref": "#/components/schemas/WorkspaceState" }, "projectId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProjectId" } ] }, "region": { "type": "string" }, "repositoryRef": { "type": [ "string", "null" ] }, "repositoryUrl": { "type": [ "string", "null" ] }, "resourceClass": { "$ref": "#/components/schemas/ResourceClass" }, "runtimeUpdateAvailable": { "type": "boolean", "description": "The runtime image is older than the one new workspaces get; the next start boots the current one." }, "sshPublicKey": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "stoppedAt": { "type": [ "string", "null" ], "format": "date-time" }, "title": { "type": "string", "description": "What people call the workspace (1–200 characters)." }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64", "description": "Settings revision; send it back with a settings change." } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "PasskeyAlgorithmDto": { "type": "object", "required": [ "type", "alg" ], "properties": { "alg": { "type": "integer", "format": "int64", "description": "A COSE algorithm: -7 (ES256), -8 (`EdDSA`) or -257 (RS256)." }, "type": { "type": "string", "description": "Always `public-key`." } } }, "PasskeyAssertionDto": { "type": "object", "description": "`AuthenticatorAssertionResponse`, as `toJSON()` gives it.", "required": [ "clientDataJSON", "authenticatorData", "signature" ], "properties": { "authenticatorData": { "type": "string" }, "clientDataJSON": { "type": "string" }, "signature": { "type": "string" }, "userHandle": { "type": [ "string", "null" ] } } }, "PasskeyAttestationDto": { "type": "object", "description": "`AuthenticatorAttestationResponse`, as `toJSON()` gives it.", "required": [ "clientDataJSON", "attestationObject" ], "properties": { "attestationObject": { "type": "string" }, "clientDataJSON": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" }, "description": "`getTransports()`, kept so later sign-ins can hint them." } } }, "PasskeyAuthenticatorSelectionDto": { "type": "object", "required": [ "residentKey", "requireResidentKey", "userVerification" ], "properties": { "requireResidentKey": { "type": "boolean" }, "residentKey": { "type": "string", "description": "Always `required`: the passkey carries the account, so signing in needs no address." }, "userVerification": { "type": "string", "description": "Always `required`." } } }, "PasskeyCreationOptionsDto": { "type": "object", "description": "`POST /api/v1/me/sign-in-methods/passkeys/options`: what `navigator.credentials.create()` needs.", "required": [ "challenge", "rp", "user", "pubKeyCredParams", "timeout", "authenticatorSelection", "attestation" ], "properties": { "attestation": { "type": "string", "description": "Always `none`." }, "authenticatorSelection": { "$ref": "#/components/schemas/PasskeyAuthenticatorSelectionDto" }, "challenge": { "type": "string" }, "excludeCredentials": { "type": "array", "items": { "$ref": "#/components/schemas/PasskeyDescriptorDto" }, "description": "The account's passkeys: the browser says one is already on this device instead of making another." }, "pubKeyCredParams": { "type": "array", "items": { "$ref": "#/components/schemas/PasskeyAlgorithmDto" } }, "rp": { "$ref": "#/components/schemas/PasskeyRpDto" }, "timeout": { "type": "integer", "format": "int32", "description": "Milliseconds.", "minimum": 0 }, "user": { "$ref": "#/components/schemas/PasskeyUserDto" } } }, "PasskeyCredentialDto": { "type": "object", "description": "A sign-in with a passkey: `PublicKeyCredential.toJSON()` after `navigator.credentials.get()`.", "required": [ "id", "type", "response" ], "properties": { "id": { "type": "string" }, "rawId": { "type": [ "string", "null" ] }, "response": { "$ref": "#/components/schemas/PasskeyAssertionDto" }, "type": { "type": "string" } } }, "PasskeyDescriptorDto": { "type": "object", "description": "A credential the browser may use or must not create again.", "required": [ "type", "id" ], "properties": { "id": { "type": "string", "description": "The credential id." }, "transports": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "description": "Always `public-key`." } } }, "PasskeyOptionsRequest": { "type": "object", "description": "`POST /api/v1/me/sign-in-methods/passkeys/options`.", "properties": { "code": { "type": [ "string", "null" ], "description": "Required when the account uses two-factor authentication: an authenticator or recovery code, since a passkey\nsigns in without one." } } }, "PasskeyRegistrationDto": { "type": "object", "description": "A new passkey: `PublicKeyCredential.toJSON()` after `navigator.credentials.create()`.", "required": [ "id", "type", "response" ], "properties": { "id": { "type": "string" }, "rawId": { "type": [ "string", "null" ] }, "response": { "$ref": "#/components/schemas/PasskeyAttestationDto" }, "type": { "type": "string" } } }, "PasskeyRequestOptionsDto": { "type": "object", "description": "`POST /auth/passkey/options`: what `navigator.credentials.get()` needs to sign in with any of this site's passkeys\n(the browser lists them; nothing is typed first).", "required": [ "challenge", "rpId", "timeout", "userVerification" ], "properties": { "allowCredentials": { "type": "array", "items": { "$ref": "#/components/schemas/PasskeyDescriptorDto" } }, "challenge": { "type": "string" }, "rpId": { "type": "string" }, "timeout": { "type": "integer", "format": "int32", "description": "Milliseconds.", "minimum": 0 }, "userVerification": { "type": "string", "description": "Always `required`: the person unlocks the passkey with their face, fingerprint or screen lock." } } }, "PasskeyRpDto": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "PasskeySignInRequest": { "type": "object", "description": "`POST /auth/passkey/finish`.", "required": [ "credential" ], "properties": { "credential": { "$ref": "#/components/schemas/PasskeyCredentialDto" }, "returnTo": { "type": [ "string", "null" ], "description": "Where to continue, as for every sign-in: a web page or `/oauth/authorize?request=…`." } } }, "PasskeyUserDto": { "type": "object", "required": [ "id", "name", "displayName" ], "properties": { "displayName": { "type": "string" }, "id": { "type": "string", "description": "The account's opaque user handle (its id's 16 bytes); never an address." }, "name": { "type": "string", "description": "The account's address, which the password manager lists the passkey under." } } }, "PaymentDto": { "type": "object", "required": [ "id", "kind", "amountCents", "currency", "face", "paidAt" ], "properties": { "amountCents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "face": { "$ref": "#/components/schemas/Amount" }, "id": { "$ref": "#/components/schemas/PaymentId" }, "kind": { "type": "string", "description": "subscription | topup | `auto_topup`" }, "paidAt": { "type": "string", "format": "date-time" }, "stripeCheckoutSessionId": { "type": [ "string", "null" ] }, "stripeInvoiceId": { "type": [ "string", "null" ] } } }, "PaymentId": { "type": "string" }, "PaymentOperationId": { "type": "string" }, "PendingSignInDto": { "type": "object", "description": "`GET /auth/connect`: a first Google or Apple sign-in whose verified address already belongs to an account, waiting\nin this browser while the person signs in to that account (which then gains it) or chooses a separate one.", "required": [ "provider", "email", "methods", "returnTo" ], "properties": { "email": { "type": "string", "description": "The address it verified, which the existing account signs in with." }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/SignInProvider" }, "description": "How the existing account signs in (`passkey` when it has one)." }, "provider": { "$ref": "#/components/schemas/SignInProvider", "description": "The provider just used." }, "returnTo": { "type": "string", "description": "Where the sign-in was going: a web page, or `/oauth/authorize?request=…` for an app's consent." } } }, "PlanCode": { "type": "string", "description": "A plan in the catalogue: `\"pro\" | \"max\" | \"ultra\" | \"team\"`." }, "PlanDto": { "type": "object", "required": [ "code", "name", "monthlyPriceUsd", "monthlyAiCredits", "monthlyCloudUnits", "diskGb", "monthlyEgressGb", "maxRunning" ], "properties": { "annualPriceUsd": { "type": [ "string", "null" ], "description": "Billed once a year: two months free. Absent when the plan is monthly only." }, "code": { "$ref": "#/components/schemas/PlanCode" }, "diskGb": { "type": "integer", "format": "int64" }, "maxRunning": { "type": "integer", "format": "int32" }, "monthlyAiCredits": { "type": "integer", "format": "int64" }, "monthlyCloudUnits": { "type": "integer", "format": "int64" }, "monthlyEgressGb": { "type": "integer", "format": "int64" }, "monthlyPriceUsd": { "type": "string" }, "name": { "type": "string" }, "seats": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SeatRangeDto", "description": "A per-seat plan (Team): prices and allowances above are per seat; checkout buys `min..=max` seats." } ] } } }, "PlanVersionId": { "type": "string", "description": "Plan catalogue version, e.g. `\"2026-11\"`." }, "PlansResponse": { "type": "object", "required": [ "version", "plans", "topups", "cloudClasses", "overage", "fundingFeePercent", "serviceFeePercent" ], "properties": { "autoTopup": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AutoTopupPolicyDto" } ] }, "cloudClasses": { "type": "array", "items": { "$ref": "#/components/schemas/CloudClassDto" } }, "fundingFeePercent": { "type": "string", "description": "Kept for older clients: the same value as `serviceFeePercent`." }, "overage": { "$ref": "#/components/schemas/OverageDto" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/PlanDto" } }, "serviceFeePercent": { "type": "string", "description": "The service fee added to every top-up, in percent of its face value." }, "topups": { "type": "array", "items": { "$ref": "#/components/schemas/TopupDto" } }, "trial": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TrialDto" } ] }, "version": { "$ref": "#/components/schemas/PlanVersionId" } } }, "PortalResponse": { "type": "object", "required": [ "portalUrl" ], "properties": { "portalUrl": { "type": "string" } } }, "ProfileArchiveId": { "type": "string" }, "ProfileRecordDto": { "type": "object", "required": [ "id", "name", "scope", "createdAt", "uploadedAt", "entryCount", "sizeBytes", "sha256" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "entryCount": { "type": "integer", "format": "int64" }, "id": { "$ref": "#/components/schemas/ProfileArchiveId" }, "name": { "type": "string" }, "scope": { "type": "string", "description": "global | local | both" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" }, "uploadedAt": { "type": "string", "format": "date-time" } } }, "ProjectDto": { "type": "object", "required": [ "id", "accountId", "name", "createdAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/ProjectId" }, "name": { "type": "string" } } }, "ProjectId": { "type": "string" }, "PublishReleaseRequest": { "type": "object", "required": [ "channel", "version", "sourceRevision", "releasedAt", "artifacts" ], "properties": { "artifacts": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "channel": { "type": "string" }, "notesUrl": { "type": [ "string", "null" ] }, "releasedAt": { "type": "string", "format": "date-time" }, "sourceRevision": { "type": "string", "description": "Full Git commit used to build every artifact." }, "version": { "type": "string" } }, "additionalProperties": false }, "PublishRemoteSessionRequest": { "type": "object", "required": [ "projectId", "threadId", "title" ], "properties": { "projectId": { "type": "string" }, "threadId": { "type": "string", "format": "uuid" }, "title": { "type": "string" } }, "additionalProperties": false }, "PublisherId": { "type": "string" }, "PublisherPageDto": { "type": "object", "description": "`GET /api/v1/marketplace/publishers/{slug}` → `{publisher, resources}`.", "required": [ "publisher", "resources" ], "properties": { "publisher": { "$ref": "#/components/schemas/PublisherRefDto" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceSummaryDto" } } } }, "PublisherRefDto": { "type": "object", "required": [ "id", "slug", "displayName", "verified" ], "properties": { "displayName": { "type": "string" }, "id": { "$ref": "#/components/schemas/PublisherId" }, "slug": { "type": "string" }, "verified": { "type": "boolean" } } }, "PushBadgeDto": { "type": "object", "description": "`GET /api/v1/push/badge`: the number the app icon shows, as the notifications set it.", "required": [ "count" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "The person's open requests (approvals and questions they can answer) that a notification told them about,\nacross every account they build in, each once however many connectors reported it. Pushes carry it as\n`aps.badge` (left out at zero).", "minimum": 0 } } }, "PushCategory": { "type": "string", "description": "A person's switch for one kind of notification. Stored per user, so every device of theirs follows one set.", "enum": [ "approvals", "completions", "failures", "billing", "security" ] }, "PushCategoryPreference": { "type": "object", "required": [ "category", "enabled" ], "properties": { "category": { "$ref": "#/components/schemas/PushCategory" }, "enabled": { "type": "boolean" } } }, "PushDeviceDto": { "type": "object", "required": [ "id", "familyId", "platform", "environment", "bundleId", "createdAt", "updatedAt", "current" ], "properties": { "appVersion": { "type": [ "string", "null" ] }, "bundleId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "current": { "type": "boolean", "description": "The device making the request." }, "environment": { "$ref": "#/components/schemas/PushEnvironment" }, "familyId": { "type": "string", "format": "uuid", "description": "The sign-in (Settings → Devices) this device belongs to." }, "id": { "type": "string", "format": "uuid" }, "lastSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "locale": { "type": [ "string", "null" ] }, "platform": { "$ref": "#/components/schemas/PushPlatform", "description": "The phone: `ios` or `android`." }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PushDevicesResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PushDeviceDto" } } } }, "PushEnvironment": { "type": "string", "description": "The APNs environment a token was issued for: development builds get `sandbox` tokens, `TestFlight` and App Store\nbuilds `production` ones. Sending a token to the other environment fails with `BadDeviceToken`.", "enum": [ "sandbox", "production" ] }, "PushPlatform": { "type": "string", "description": "The phone a device or Live Activity registration is for, and so the push service that delivers to it: Apple's\nfor `ios`, Firebase Cloud Messaging for `android`. Registrations that predate Android read as `ios`.", "enum": [ "ios", "android" ] }, "PushPreferencesDto": { "type": "object", "required": [ "available", "platforms", "categories" ], "properties": { "available": { "type": "boolean", "description": "Whether this Cloud delivers pushes at all (a provider other than `log` is configured). A phone receives them\nwhen this is true and its platform is in `platforms`." }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/PushCategoryPreference" }, "description": "Every category, in the order settings show them: `approvals`, `completions`, `failures`, `billing`,\n`security`." }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/PushPlatform" }, "description": "The phones this Cloud accepts device registrations for (`ios`, `android`): both while it delivers nothing\n(`log`) or writes a development outbox (`file`), otherwise those it has a push service for." } } }, "ReadyResponse": { "type": "object", "description": "`GET /readyz`.", "required": [ "status", "database", "migrationsCurrent", "details" ], "properties": { "database": { "type": "boolean" }, "details": { "description": "api: `{\"oidcDiscovery\":bool,\"plansLoaded\":bool}`; router: `{\"pricebookPublished\":bool,\"spoolPending\":n}`;\nworker: `{\"schedulesLease\":bool}`" }, "migrationsCurrent": { "type": "boolean" }, "status": { "type": "string", "description": "\"ok\" | \"degraded\"" } } }, "RegisterLiveActivityRequest": { "type": "object", "description": "`PUT /api/v1/push/activities/{activityId}`: a chat the phone follows live (the id is the app's: iOS its\n`ActivityKit` id, Android its ongoing notification's), and the token its updates go to.", "required": [ "token", "bundleId", "target", "threadId" ], "properties": { "bundleId": { "type": "string", "description": "The bundle identifier (iOS) or package name (Android; also accepted as `appId`)." }, "environment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PushEnvironment", "description": "iOS (required): as for the device. Android: ignored and stored as `production`." } ] }, "platform": { "$ref": "#/components/schemas/PushPlatform", "description": "The phone: `ios` (the default) or `android`." }, "target": { "$ref": "#/components/schemas/LiveActivityTargetDto" }, "threadId": { "type": "string", "format": "uuid", "description": "The root chat." }, "token": { "type": "string", "description": "iOS: the Live Activity's own push token (hex). Android: the device's FCM registration token." } } }, "RegisterPushDeviceRequest": { "type": "object", "description": "`PUT /api/v1/push/devices/current`: the push token of the app making the request.", "required": [ "token", "bundleId" ], "properties": { "appVersion": { "type": [ "string", "null" ] }, "bundleId": { "type": "string", "description": "The app's bundle identifier (iOS) or package name (Android; also accepted as `appId`); must be an app this\nCloud sends to." }, "deviceLabel": { "type": [ "string", "null" ], "description": "Names the sign-in in Settings → Devices when it has no name yet, e.g. `iPhone · iOS 26` or\n`Pixel 8 · Android 16`." }, "environment": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PushEnvironment", "description": "iOS (required): `sandbox` for development builds, `production` for `TestFlight` and App Store builds. Android:\nignored and stored as `production` (FCM has no sandbox)." } ] }, "locale": { "type": [ "string", "null" ], "description": "BCP 47, e.g. `fr-FR`." }, "platform": { "$ref": "#/components/schemas/PushPlatform", "description": "The phone: `ios` (the default) or `android`. Must be one of `platforms` in `GET /api/v1/push/preferences`, or\nthe answer is `409 push_platform_unavailable`." }, "token": { "type": "string", "description": "iOS: the APNs device token as hex (64–200 characters; stored lowercase). Android: the FCM registration token\n(20–4096 letters, digits, `_`, `:` or `-`; kept exactly as sent)." } } }, "RegisterRemoteHostRequest": { "type": "object", "required": [ "id", "name", "mode" ], "properties": { "accountId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AccountId" } ] }, "id": { "type": "string", "format": "uuid", "description": "Stable installation ID. Re-registering never revives revoked access." }, "metadata": {}, "mode": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "ReleaseManifestResponse": { "type": "object", "required": [ "channel", "manifest", "publishedAt" ], "properties": { "channel": { "type": "string" }, "manifest": {}, "publishedAt": { "type": "string", "format": "date-time" } } }, "ReleasePublication": { "type": "object", "required": [ "id", "current", "release" ], "properties": { "current": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "release": { "$ref": "#/components/schemas/ReleaseManifestResponse" } } }, "ReleaseUpload": { "type": "object", "description": "An immutable, checksum-verified payload. The API serves uploads only once published; `url` is where the\npublished file downloads: the public release domain for files in the release bucket, else the API.", "required": [ "id", "version", "product", "file", "kind", "os", "arch", "size", "sha256", "url" ], "properties": { "arch": { "type": "string" }, "file": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "os": { "type": "string" }, "product": { "type": "string" }, "sha256": { "type": "string" }, "size": { "type": "integer", "format": "int64" }, "url": { "type": "string" }, "version": { "type": "string" } } }, "RemoteHostDto": { "type": "object", "required": [ "id", "accountId", "name", "mode", "connected", "metadata", "createdAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "connected": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": {}, "mode": { "type": "string", "description": "`host` exposes projects; `sessions` exposes only explicitly published chats." }, "name": { "type": "string" } } }, "RemoteProjectError": { "type": "object", "description": "`remote_project` failure shape (verbatim from remote.rs):\n`{\"error\":{\"code\":\"remote_project\",\"message\":\"…\",\"retryable\":false}}`", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/RemoteProjectErrorBody" } } }, "RemoteProjectErrorBody": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } }, "RemoteSessionDto": { "type": "object", "required": [ "id", "hostId", "accountId", "projectId", "threadId", "title", "connected", "createdAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "connected": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "hostId": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string" }, "threadId": { "type": "string", "format": "uuid" }, "title": { "type": "string" } } }, "RemoveSignInMethodRequest": { "type": "object", "description": "`POST /api/v1/me/sign-in-methods/{id}/remove`.", "properties": { "code": { "type": [ "string", "null" ], "description": "Required when `mfaRequired`: an authenticator or recovery code." } } }, "ResolveAiOutputReportRequest": { "type": "object", "description": "`POST /internal/ops/reports/ai-output/{id}/resolve`: what was done about it, 1–1,000 characters when given.", "properties": { "resolution": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "ResourceClass": { "type": "string", "description": "Wire form equals [`ResourceClass::id`] (`\"shared-2cpu-4gb\"` …), the `cloud_classes[].id` of the plan catalogue.", "enum": [ "shared-2cpu-4gb", "performance-2cpu-4gb", "performance-4cpu-8gb" ] }, "ResourceDetailDto": { "allOf": [ { "$ref": "#/components/schemas/ResourceSummaryDto" }, { "type": "object", "required": [ "notes", "versions", "collections" ], "properties": { "activeVersion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VersionDetailDto" } ] }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionRefDto" } }, "homepageUrl": { "type": [ "string", "null" ] }, "notes": { "type": "string" }, "repositoryUrl": { "type": [ "string", "null" ] }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/VersionSummaryDto" } } } } ] }, "ResourceId": { "type": "string" }, "ResourceKind": { "type": "string", "enum": [ "plugin", "skill", "agent", "mcp", "extension" ] }, "ResourceSummaryDto": { "type": "object", "required": [ "id", "kind", "slug", "publisher", "name", "summary", "keywords", "visibility", "updatedAt" ], "properties": { "category": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/ResourceId" }, "keywords": { "type": "array", "items": { "type": "string" } }, "kind": { "$ref": "#/components/schemas/ResourceKind" }, "latestVersion": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VersionSummaryDto" } ] }, "name": { "type": "string" }, "publisher": { "$ref": "#/components/schemas/PublisherRefDto" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "visibility": { "$ref": "#/components/schemas/Visibility" } } }, "RestoreRequest": { "type": "object", "required": [ "snapshotId" ], "properties": { "snapshotId": { "$ref": "#/components/schemas/SnapshotId" } } }, "ReviewDecision": { "type": "string", "enum": [ "approved", "rejected", "yanked" ] }, "ReviewStatus": { "type": "string", "enum": [ "draft", "submitted", "in_review", "approved", "rejected", "yanked" ] }, "ReviewVersionRequest": { "type": "object", "description": "`POST /internal/ops/marketplace/versions/{id}/review` (§5.3): the moderation decision that moves a validated\nsubmission out of `in_review`. `approved` also moves the resource's active/latest pointers; `yanked` needs a\n`reason` and falls the active pointer back to the newest still-approved version.", "required": [ "decision", "reviewerId" ], "properties": { "decision": { "$ref": "#/components/schemas/ReviewDecision", "description": "`approved` | `rejected` | `yanked`" }, "notes": { "type": [ "string", "null" ] }, "reviewerId": { "$ref": "#/components/schemas/UserId", "description": "The moderator; recorded on `reviews.reviewer_id`, so it must be an existing user." } } }, "ReviewVersionResponse": { "type": "object", "required": [ "version" ], "properties": { "version": { "$ref": "#/components/schemas/VersionSummaryDto" } } }, "RouterDto": { "type": "object", "required": [ "id", "accountId", "name", "description", "isDefault", "credentialMode", "configuredProviders", "providerSettings", "routerUrl", "revision", "createdAt", "updatedAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "configuredProviders": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "credentialMode": { "type": "string", "description": "system: Cloud credits; byok: upstream provider bills the customer's key." }, "description": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "isDefault": { "type": "boolean" }, "modelAllowlist": { "type": [ "array", "null" ], "items": { "type": "string" } }, "name": { "type": "string" }, "providerSettings": { "type": "object", "description": "Non-secret connection settings, keyed by provider ID.", "additionalProperties": { "$ref": "#/components/schemas/RouterProviderSettings" }, "propertyNames": { "type": "string" } }, "revision": { "type": "integer", "format": "int64" }, "routerUrl": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RouterKeyDto": { "type": "object", "required": [ "keyId", "prefix", "label", "scopeKind", "policy", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "keyId": { "$ref": "#/components/schemas/RouterKeyId" }, "label": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "policy": { "$ref": "#/components/schemas/KeyPolicyDto" }, "prefix": { "type": "string", "description": "\"hcr_\"" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "scopeKind": { "type": "string", "description": "user | workspace" }, "workspaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceId" } ] } } }, "RouterKeyId": { "type": "string", "description": "Public part of an `hcr_` router key (16 lowercase hex characters)." }, "RouterProviderDto": { "type": "object", "required": [ "id", "name", "credentialLabel", "fields" ], "properties": { "credentialLabel": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "name": { "type": "string" } } }, "RouterProviderSettings": { "type": "object", "description": "Safe connection parameters. Endpoints are constructed from a trusted provider registry.", "properties": { "models": { "type": "array", "items": { "type": "string" }, "description": "Upstream model/deployment IDs to advertise, including providers without discovery APIs." }, "project": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "resource": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "RouterProvidersResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RouterProviderDto" } } } }, "RoutersResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RouterDto" } } } }, "SaveWorkspaceAgentRequest": { "type": "object", "description": "`POST /api/v1/workspaces/{id}/save-agent`: a new Cloud agent template from the workspace's configuration.", "required": [ "name", "version" ], "properties": { "description": { "type": "string" }, "includeEnvironment": { "type": "boolean" }, "name": { "type": "string" }, "version": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "SeatRangeDto": { "type": "object", "required": [ "min", "max" ], "properties": { "max": { "type": "integer", "format": "int32" }, "min": { "type": "integer", "format": "int32" } } }, "SeatsDto": { "type": "object", "description": "A team's seats: what its Team plan pays for, who holds them and who is invited.", "required": [ "members", "pendingInvitations" ], "properties": { "members": { "type": "integer", "format": "int64" }, "pendingInvitations": { "type": "integer", "format": "int64" }, "seats": { "type": [ "integer", "null" ], "format": "int32", "description": "Seats on the current per-seat plan; absent without one (members are then not limited)." } } }, "SessionId": { "type": "string" }, "SessionSummaryDto": { "type": "object", "required": [ "id", "createdAt", "lastSeenAt", "expiresAt", "current" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "current": { "type": "boolean" }, "expiresAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/SessionId" }, "label": { "type": [ "string", "null" ] }, "lastSeenAt": { "type": "string", "format": "date-time" }, "userAgent": { "type": [ "string", "null" ] } } }, "SetRouterCredentialRequest": { "type": "object", "required": [ "revision", "apiKey" ], "properties": { "apiKey": { "type": [ "string", "null" ], "description": "null removes this provider's key. Empty strings are rejected." }, "revision": { "type": "integer", "format": "int64" }, "settings": { "$ref": "#/components/schemas/RouterProviderSettings" } }, "additionalProperties": false }, "SignInMethodDto": { "type": "object", "description": "One of the caller's sign-in methods.", "required": [ "id", "provider" ], "properties": { "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "credentialId": { "type": [ "string", "null" ], "description": "A passkey's credential id (base64url), so the page can tell the password manager which ones still sign in." }, "email": { "type": [ "string", "null" ] }, "hasPassword": { "type": "boolean", "description": "The email credential has a password (links and codes work either way)." }, "id": { "type": "string", "description": "The identity's or passkey's id, or `email` for the email credential." }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": [ "string", "null" ], "description": "A passkey's name: where it is kept (`iCloud Keychain`, `Google Password Manager`, `1Password`…), or `Passkey`." }, "privateEmail": { "type": "boolean", "description": "An Apple private relay address (\"Hide My Email\")." }, "provider": { "$ref": "#/components/schemas/SignInProvider" }, "synced": { "type": "boolean", "description": "A passkey that syncs to the person's other devices through its password manager." } } }, "SignInMethodsDto": { "type": "object", "description": "`GET /api/v1/me/sign-in-methods`: how the caller signs in, and what this Cloud can add.", "required": [ "methods", "googleEnabled", "appleEnabled", "mfaRequired" ], "properties": { "appleEnabled": { "type": "boolean", "description": "This Cloud offers Sign in with Apple." }, "googleEnabled": { "type": "boolean", "description": "This Cloud offers Continue with Google." }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/SignInMethodDto" }, "description": "Google and Apple identities (oldest first), the email credential, then passkeys (oldest first)." }, "mfaRequired": { "type": "boolean", "description": "Removing a method asks for a current two-factor code." }, "passkeysEnabled": { "type": "boolean", "description": "This Cloud's web origin can hold passkeys (a domain over https, or `localhost`)." } } }, "SignInProvider": { "type": "string", "description": "A way to sign in to an account (ADR-0016).", "enum": [ "google", "apple", "email", "passkey" ] }, "SignInResponse": { "type": "object", "description": "The continuation after a completed sign-in step.", "properties": { "mfaRequired": { "type": "boolean", "description": "The first factor was right; the sign-in now waits for a code (`POST /auth/mfa/verify`)." }, "redirectTo": { "type": [ "string", "null" ], "description": "Where the browser goes next; absent while `mfaRequired`." } } }, "SignedArtifactDto": { "type": "object", "required": [ "url", "expiresAt", "sha256", "sizeBytes", "contentType" ], "properties": { "contentType": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" }, "url": { "type": "string" } } }, "SnapshotDto": { "type": "object", "required": [ "id", "workspaceId", "kind", "status", "createdAt" ], "properties": { "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/SnapshotId" }, "kind": { "type": "string", "description": "provider | export" }, "sizeBytes": { "type": [ "integer", "null" ], "format": "int64" }, "status": { "type": "string" }, "workspaceId": { "$ref": "#/components/schemas/WorkspaceId" } } }, "SnapshotId": { "type": "string" }, "StopReason": { "type": "string", "enum": [ "user_request", "idle", "allowance_exhausted", "reconcile", "delete", "provider_failure", "operator" ] }, "StripeWebhookAck": { "type": "object", "description": "`POST /webhooks/stripe` → `{\"received\":true}`.", "required": [ "received" ], "properties": { "received": { "type": "boolean" } } }, "SubmissionDto": { "type": "object", "required": [ "id", "status", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/SubmissionId" }, "resourceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ResourceId" } ] }, "status": { "type": "string", "description": "received | validating | rejected | `in_review` | approved" }, "validation": {}, "versionId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VersionId" } ] } } }, "SubmissionId": { "type": "string" }, "SubmissionSource": { "oneOf": [ { "type": "object", "required": [ "artifactId", "kind" ], "properties": { "artifactId": { "$ref": "#/components/schemas/ArtifactId" }, "kind": { "type": "string", "enum": [ "upload" ] } } }, { "type": "object", "required": [ "url", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "git" ] }, "path": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, { "type": "object", "required": [ "npmSpec", "extensionType", "kind" ], "properties": { "extensionType": { "$ref": "#/components/schemas/ExtensionType" }, "kind": { "type": "string", "enum": [ "npm" ] }, "npmSpec": { "type": "string" } } }, { "type": "object", "required": [ "configTemplate", "kind" ], "properties": { "configTemplate": {}, "envPlaceholders": { "type": "array", "items": { "$ref": "#/components/schemas/EnvPlaceholderDto" } }, "kind": { "type": "string", "enum": [ "mcp_template" ] } } } ] }, "SubscriptionDto": { "type": "object", "required": [ "id", "planCode", "planVersion", "status", "cancelAtPeriodEnd" ], "properties": { "billingInterval": { "type": "string", "description": "`month | year`" }, "cancelAtPeriodEnd": { "type": "boolean" }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "currentPeriodStart": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "$ref": "#/components/schemas/SubscriptionId" }, "planCode": { "$ref": "#/components/schemas/PlanCode" }, "planVersion": { "$ref": "#/components/schemas/PlanVersionId" }, "seats": { "type": "integer", "format": "int32", "description": "Seats of a per-seat plan; 1 otherwise." }, "status": { "type": "string", "description": "active | `past_due` | canceled | incomplete | trialing | unpaid | none" }, "stripeSubscriptionId": { "type": [ "string", "null" ] } } }, "SubscriptionId": { "type": "string" }, "TariffStatus": { "type": "string", "enum": [ "active", "disabled" ] }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64", "description": "600", "minimum": 0 }, "refresh_token": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "token_type": { "type": "string", "description": "\"Bearer\"" } } }, "TopupDto": { "type": "object", "required": [ "code", "faceUsd", "credits", "priceUsd" ], "properties": { "code": { "type": "string" }, "credits": { "type": "integer", "format": "int64" }, "faceUsd": { "type": "string" }, "priceUsd": { "type": "string" } } }, "TransactionId": { "type": "string" }, "TrialDto": { "type": "object", "description": "The one-time Cloud trial: claimed by saving a card; nothing is charged.", "required": [ "days", "aiCredits", "cloudUnits", "diskGb", "maxRunning" ], "properties": { "aiCredits": { "type": "integer", "format": "int64" }, "cloudUnits": { "type": "integer", "format": "int64" }, "days": { "type": "integer", "format": "int64" }, "diskGb": { "type": "integer", "format": "int64" }, "maxRunning": { "type": "integer", "format": "int32" } } }, "Unit": { "type": "string", "description": "Ledger unit of a bucket / ledger entry. Serialized `snake_case`; DB enum `ledger_unit`.", "enum": [ "nanos", "unit_seconds", "bytes" ] }, "UpdateAccountApiKeyRequest": { "type": "object", "properties": { "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "A future expiry, at most 366 days away. Cannot make a key non-expiring." }, "label": { "type": [ "string", "null" ] }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KeyPolicyDto" } ] }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "additionalProperties": false }, "UpdateAccountRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } } }, "UpdateAutoTopup": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "thresholdCredits": { "type": [ "integer", "null" ], "format": "int64" }, "topupCode": { "type": [ "string", "null" ] } } }, "UpdateCloudAgentRequest": { "type": "object", "required": [ "version", "name", "configuration" ], "properties": { "configuration": { "$ref": "#/components/schemas/AgentConfiguration" }, "description": { "type": "string" }, "environment": { "type": [ "object", "null" ], "description": "Write-only. Omit on update to retain existing secret values; empty map clears them.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "name": { "type": "string" }, "version": { "type": "integer", "format": "int64", "description": "Required optimistic revision; existing workspaces always retain their captured version." } }, "additionalProperties": false }, "UpdateCloudScheduleRequest": { "type": "object", "required": [ "version" ], "properties": { "at": { "type": [ "string", "null" ], "format": "date-time", "description": "Moves the next run (must be in the future)." }, "enabled": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "prompt": { "type": [ "string", "null" ] }, "timing": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudScheduleTiming", "description": "Replaces the whole cadence: one-off, interval or calendar, with its time zone." } ] }, "version": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "UpdateMemberRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/MembershipRole" } } }, "UpdatePushPreferencesRequest": { "type": "object", "description": "`PATCH /api/v1/push/preferences`: the categories to change; the others keep their setting.", "required": [ "categories" ], "properties": { "categories": { "type": "array", "items": { "$ref": "#/components/schemas/PushCategoryPreference" } } } }, "UpdateRemoteHostRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } }, "additionalProperties": false }, "UpdateRouterRequest": { "type": "object", "required": [ "revision", "name", "credentialMode" ], "properties": { "credentialMode": { "type": "string" }, "description": { "type": "string" }, "modelAllowlist": { "type": [ "array", "null" ], "items": { "type": "string" } }, "name": { "type": "string" }, "revision": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "UpdateWalletRequest": { "type": "object", "properties": { "autoTopup": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UpdateAutoTopup", "description": "Turning automatic top-ups on also turns overage on: purchased credits only pay with it." } ] }, "overageOptIn": { "type": [ "boolean", "null" ] } } }, "UpdateWorkspaceRequest": { "type": "object", "description": "`PATCH /api/v1/workspaces/{id}`: rename, change settings (with `version`; they apply at the next start, so the\nworkspace must be stopped), or the idle timeout and keep-alive.", "properties": { "configuration": {}, "environment": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "idleTimeoutSecs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "keepAliveUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "absent = unchanged, null = clear" }, "name": { "type": [ "string", "null" ], "description": "Deprecated alias of `title`.", "deprecated": true }, "title": { "type": [ "string", "null" ] }, "version": { "type": [ "integer", "null" ], "format": "int64", "description": "Required for configuration/environment updates." } }, "additionalProperties": false }, "UploadArtifactResponse": { "type": "object", "required": [ "artifactId", "sha256", "sizeBytes" ], "properties": { "artifactId": { "$ref": "#/components/schemas/ArtifactId" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" } } }, "UsageArch": { "type": "string", "enum": [ "aarch64", "x86_64", "other" ] }, "UsageBuild": { "type": "string", "enum": [ "release", "debug" ] }, "UsageClientDto": { "type": "object", "required": [ "version", "os", "arch", "build" ], "properties": { "arch": { "$ref": "#/components/schemas/UsageArch" }, "build": { "$ref": "#/components/schemas/UsageBuild" }, "os": { "$ref": "#/components/schemas/UsageOs" }, "version": { "type": "string", "description": "1–64 characters of `[A-Za-z0-9._+-]`, e.g. `0.1.1-preview.1`." } }, "additionalProperties": false }, "UsageDayReport": { "type": "object", "description": "One day as the client counted it (in its local calendar).", "required": [ "day", "chats", "turns", "completedTurns", "failedTurns", "interruptedTurns", "subagentTurns", "scheduledTurns", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "toolCalls", "toolErrors", "fileChanges", "linesAdded", "linesRemoved" ], "properties": { "cacheReadTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "chats": { "type": "integer", "format": "int64", "minimum": 0 }, "completedTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "costUsd": { "type": [ "number", "null" ], "format": "double", "description": "The client's cost estimate in USD; omitted or `null` when unknown." }, "day": { "type": "string", "format": "date", "description": "`YYYY-MM-DD`", "example": "2026-10-10" }, "failedTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "fileChanges": { "type": "integer", "format": "int64", "minimum": 0 }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "interruptedTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "linesAdded": { "type": "integer", "format": "int64", "minimum": 0 }, "linesRemoved": { "type": "integer", "format": "int64", "minimum": 0 }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/UsageModelReport" }, "description": "At most 50, unique by `(provider, model)`." }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "scheduledTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "subagentTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "toolCalls": { "type": "integer", "format": "int64", "minimum": 0 }, "toolErrors": { "type": "integer", "format": "int64", "minimum": 0 }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/UsageToolReport" }, "description": "At most 64, unique by `name`." }, "turns": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "UsageDayTotalsDto": { "type": "object", "required": [ "day", "chats", "turns", "completedTurns", "failedTurns", "interruptedTurns", "subagentTurns", "scheduledTurns", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "toolCalls", "toolErrors", "fileChanges", "linesAdded", "linesRemoved" ], "properties": { "cacheReadTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "chats": { "type": "integer", "format": "int64", "minimum": 0 }, "completedTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "costUsd": { "type": [ "number", "null" ], "format": "double", "description": "Absent when no installation knew its cost that day." }, "day": { "type": "string", "format": "date" }, "failedTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "fileChanges": { "type": "integer", "format": "int64", "minimum": 0 }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "interruptedTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "linesAdded": { "type": "integer", "format": "int64", "minimum": 0 }, "linesRemoved": { "type": "integer", "format": "int64", "minimum": 0 }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "scheduledTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "subagentTurns": { "type": "integer", "format": "int64", "minimum": 0 }, "toolCalls": { "type": "integer", "format": "int64", "minimum": 0 }, "toolErrors": { "type": "integer", "format": "int64", "minimum": 0 }, "turns": { "type": "integer", "format": "int64", "minimum": 0 } } }, "UsageInstallDto": { "type": "object", "description": "One of the caller's installations. The install id is shortened: the full id is the app's own secret.", "required": [ "installId", "version", "os", "arch", "lastSeenAt" ], "properties": { "arch": { "type": "string", "description": "`aarch64|x86_64|other`" }, "installId": { "type": "string", "description": "The first 8 hex digits of the install id." }, "lastSeenAt": { "type": "string", "format": "date-time" }, "os": { "type": "string", "description": "`macos|linux|windows|other`" }, "version": { "type": "string" } } }, "UsageItemDto": { "type": "object", "required": [ "kind", "id", "occurredAt", "quantities", "amount", "bucketKinds", "settlementRef" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "bucketKinds": { "type": "array", "items": { "$ref": "#/components/schemas/BucketKind" } }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "`ai_request` | compute | storage | egress" }, "model": { "type": [ "string", "null" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "provider": { "type": [ "string", "null" ] }, "quantities": { "description": "`{\"uncachedInputTokens\":..,\"cachedInputTokens\":..,\"cacheWriteTokens\":..,\"outputTokens\":..}` | `{\"unitSeconds\":..,\"multiplier\":..}`" }, "requestId": { "type": [ "string", "null" ] }, "settlementRef": { "type": "string", "description": "The idempotency key the item settled under: `usage_settlements.settlement_id` for `ai_request`,\n`
.settlement_ref` for the compute/storage/egress intervals. A compute interval written by the\nstop path is `compute::final` (§7 row 8), which is the only way to observe the final\nsettlement over HTTP." }, "workspaceId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceId" } ] } } }, "UsageModelReport": { "type": "object", "required": [ "provider", "model", "turns", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "properties": { "cacheReadTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "costUsd": { "type": [ "number", "null" ], "format": "double" }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "model": { "type": "string", "description": "1–100 characters of `[A-Za-z0-9._:/@+-]`." }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "provider": { "type": "string", "description": "1–100 characters of `[A-Za-z0-9._:/@+-]`." }, "turns": { "type": "integer", "format": "int64", "minimum": 0 } }, "additionalProperties": false }, "UsageModelTotalsDto": { "type": "object", "required": [ "provider", "model", "turns", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "properties": { "cacheReadTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "costUsd": { "type": [ "number", "null" ], "format": "double" }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "model": { "type": "string" }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "provider": { "type": "string" }, "turns": { "type": "integer", "format": "int64", "minimum": 0 } } }, "UsageOpsDayDto": { "type": "object", "required": [ "day", "activeInstalls", "linkedUsers", "anonymousInstalls", "chats", "turns", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "properties": { "activeInstalls": { "type": "integer", "format": "int64", "description": "Installations that reported this day.", "minimum": 0 }, "anonymousInstalls": { "type": "integer", "format": "int64", "description": "Those installations that are not linked to anyone.", "minimum": 0 }, "cacheReadTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "chats": { "type": "integer", "format": "int64", "minimum": 0 }, "costUsd": { "type": [ "number", "null" ], "format": "double" }, "day": { "type": "string", "format": "date" }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "linkedUsers": { "type": "integer", "format": "int64", "description": "Distinct users those installations are linked to.", "minimum": 0 }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "turns": { "type": "integer", "format": "int64", "minimum": 0 } } }, "UsageOpsResponse": { "type": "object", "description": "`GET /internal/ops/telemetry/usage`: totals across every installation. User ids only, never emails.", "required": [ "from", "to", "days", "models", "tools", "versions", "os", "users" ], "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageOpsDayDto" }, "description": "The days of the window with at least one report, oldest first." }, "from": { "type": "string", "format": "date" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/UsageModelTotalsDto" } }, "os": { "type": "array", "items": { "$ref": "#/components/schemas/UsageValueCountDto" }, "description": "Installations active in the window by operating system, most common first." }, "to": { "type": "string", "format": "date" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/UsageToolTotalsDto" } }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UsageUserTotalsDto" }, "description": "The 50 linked users with the most tokens (input + output + cache read + cache write) in the window." }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/UsageValueCountDto" }, "description": "Installations active in the window by their current client version, most common first." } } }, "UsageOs": { "type": "string", "enum": [ "macos", "linux", "windows", "other" ] }, "UsageReportRequest": { "type": "object", "description": "`POST /api/v1/telemetry/usage`: one installation's latest snapshot of 1–31 days.\n\nEach day **replaces** what was stored for `(installId, day)`; clients resend the last week every few hours and\nthe server never adds two snapshots of a day together. Every count is an integer from 0 to 10^15; `costUsd` is\na finite number from 0 to 10^9, or omitted/`null` when the client does not know it.", "required": [ "schemaVersion", "installId", "client", "days" ], "properties": { "client": { "$ref": "#/components/schemas/UsageClientDto" }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDayReport" }, "description": "1–31 days with distinct `day` values, each between today−35 and today+1 (UTC)." }, "installId": { "type": "string", "format": "uuid", "description": "A random id the app generates once per installation." }, "schemaVersion": { "type": "integer", "format": "int32", "description": "Always `1`.", "minimum": 0 } }, "additionalProperties": false }, "UsageReportResponse": { "type": "object", "description": "`202` to [`UsageReportRequest`].", "required": [ "accepted", "days", "linked" ], "properties": { "accepted": { "type": "boolean" }, "days": { "type": "integer", "format": "int32", "description": "How many days were stored.", "minimum": 0 }, "linked": { "type": "boolean", "description": "The report carried a valid bearer and the installation is now linked to that user." } } }, "UsageSummaryResponse": { "type": "object", "description": "`GET /api/v1/telemetry/usage`: the caller's statistics summed over every installation linked to them.", "required": [ "from", "to", "days", "models", "tools", "installs" ], "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDayTotalsDto" }, "description": "The days of the window with at least one report, oldest first." }, "from": { "type": "string", "format": "date" }, "installs": { "type": "array", "items": { "$ref": "#/components/schemas/UsageInstallDto" }, "description": "The installations linked to the caller, most recently seen first." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/UsageModelTotalsDto" }, "description": "The models with the most turns in the window." }, "to": { "type": "string", "format": "date" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/UsageToolTotalsDto" }, "description": "The most-called tools in the window." } } }, "UsageToolReport": { "type": "object", "required": [ "name", "calls", "errors" ], "properties": { "calls": { "type": "integer", "format": "int64", "minimum": 0 }, "errors": { "type": "integer", "format": "int64", "minimum": 0 }, "name": { "type": "string", "description": "1–100 characters of `[A-Za-z0-9._:/@+-]`." } }, "additionalProperties": false }, "UsageToolTotalsDto": { "type": "object", "required": [ "name", "calls", "errors" ], "properties": { "calls": { "type": "integer", "format": "int64", "minimum": 0 }, "errors": { "type": "integer", "format": "int64", "minimum": 0 }, "name": { "type": "string" } } }, "UsageUserTotalsDto": { "type": "object", "required": [ "userId", "installs", "turns", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens" ], "properties": { "cacheReadTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cacheWriteTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "costUsd": { "type": [ "number", "null" ], "format": "double" }, "inputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "installs": { "type": "integer", "format": "int64", "description": "Their installations that reported in the window.", "minimum": 0 }, "outputTokens": { "type": "integer", "format": "int64", "minimum": 0 }, "turns": { "type": "integer", "format": "int64", "minimum": 0 }, "userId": { "$ref": "#/components/schemas/UserId" } } }, "UsageValueCountDto": { "type": "object", "required": [ "value", "installs" ], "properties": { "installs": { "type": "integer", "format": "int64", "minimum": 0 }, "value": { "type": "string" } } }, "UserDto": { "type": "object", "required": [ "id", "displayName", "emailVerified", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "displayName": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "emailVerified": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/UserId" } } }, "UserId": { "type": "string" }, "VersionDetailDto": { "allOf": [ { "$ref": "#/components/schemas/VersionSummaryDto" }, { "type": "object", "required": [ "compatibility", "capabilities", "inventory", "kindMetadata" ], "properties": { "artifact": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ArtifactRefDto" } ] }, "capabilities": { "$ref": "#/components/schemas/Capabilities" }, "changelog": { "type": [ "string", "null" ] }, "compatibility": { "$ref": "#/components/schemas/CompatibilityDto" }, "inventory": {}, "kindMetadata": {}, "licenseSpdx": { "type": [ "string", "null" ] } } } ] }, "VersionId": { "type": "string" }, "VersionSummaryDto": { "type": "object", "required": [ "id", "number", "status", "yanked", "createdAt" ], "properties": { "contentDigest": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "id": { "$ref": "#/components/schemas/VersionId" }, "number": { "type": "integer", "format": "int32" }, "semver": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ReviewStatus" }, "yanked": { "type": "boolean" } } }, "Visibility": { "type": "string", "enum": [ "public", "private" ] }, "WalletDto": { "type": "object", "description": "`GET /api/v1/billing/wallet`; the §3.2.4 example shows a running workspace with the 10 unit-second\n`ComputeLead` hold of §7 step 3.", "required": [ "billingAccountId", "overageOptIn", "status", "buckets", "includedAi", "purchased", "heldReserve", "cloudUnitSecondsAvailable", "cloudUnitSecondsReserved", "egressBytesAvailable", "egressBytesReserved" ], "properties": { "aiSpendLast7Days": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Amount", "description": "Model spend over the last 7 days: divided by 7, the recent daily pace behind \"about N days left\"." } ] }, "autoTopup": { "$ref": "#/components/schemas/AutoTopupDto" }, "billingAccountId": { "$ref": "#/components/schemas/BillingAccountId" }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/BucketDto" } }, "cloudUnitSecondsAvailable": { "type": "integer", "format": "int64" }, "cloudUnitSecondsReserved": { "type": "integer", "format": "int64" }, "egressBytesAvailable": { "type": "integer", "format": "int64" }, "egressBytesReserved": { "type": "integer", "format": "int64" }, "hasPaymentMethod": { "type": "boolean", "description": "A card is saved for automatic top-ups." }, "heldReserve": { "$ref": "#/components/schemas/Amount", "description": "Σ holds whose unit is nanos ONLY (`included_ai` + purchased); never converts unit-second/byte holds" }, "includedAi": { "$ref": "#/components/schemas/Amount" }, "overageOptIn": { "type": "boolean" }, "purchased": { "$ref": "#/components/schemas/Amount" }, "resetsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "active | suspended | frozen" }, "trialAvailable": { "type": "boolean", "description": "The account can still claim the one-time trial." }, "trialRefused": { "type": "boolean", "description": "A trial checkout saved a card that had already been used for a trial, so no trial started." } } }, "WorkspaceAgent": { "type": "object", "required": [ "prompt" ], "properties": { "description": { "type": "string" }, "hidden": { "type": "boolean" }, "mode": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "permission": {}, "prompt": { "type": "string" }, "steps": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "tools": { "type": "object", "additionalProperties": { "type": "boolean" }, "propertyNames": { "type": "string" } } }, "additionalProperties": false }, "WorkspaceDto": { "type": "object", "required": [ "id", "accountId", "title", "name", "configuration", "version", "environmentNames", "region", "resourceClass", "diskGb", "imageRef", "desiredState", "observedState", "idleTimeoutSecs", "createdAt", "updatedAt" ], "properties": { "accountId": { "$ref": "#/components/schemas/AccountId" }, "agentSnapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CloudAgentDto", "description": "That template as it was when the workspace was created (immutable provenance)." } ] }, "cloudAgentId": { "type": [ "string", "null" ], "format": "uuid", "description": "The Cloud agent template the workspace started from, if any." }, "configuration": { "$ref": "#/components/schemas/AgentConfiguration" }, "createdAt": { "type": "string", "format": "date-time" }, "desiredState": { "$ref": "#/components/schemas/DesiredState" }, "diskGb": { "type": "integer", "format": "int64" }, "environmentNames": { "type": "array", "items": { "type": "string" } }, "failureReason": { "type": [ "string", "null" ] }, "generation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GenerationDto" } ] }, "id": { "$ref": "#/components/schemas/WorkspaceId" }, "idleTimeoutSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "imageRef": { "type": "string" }, "keepAliveUntil": { "type": [ "string", "null" ], "format": "date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "format": "date-time" }, "launch": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WorkspaceLaunchDto", "description": "How Cloud is delivering the workspace's first message; absent on workspaces created without one." } ] }, "name": { "type": "string", "description": "The machine's slug. Kept for clients made before titles; show `title` instead.", "deprecated": true }, "observedState": { "$ref": "#/components/schemas/WorkspaceState" }, "projectId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProjectId" } ] }, "region": { "type": "string" }, "repositoryRef": { "type": [ "string", "null" ] }, "repositoryUrl": { "type": [ "string", "null" ] }, "resourceClass": { "$ref": "#/components/schemas/ResourceClass" }, "runtimeUpdateAvailable": { "type": "boolean", "description": "The runtime image is older than the one new workspaces get; the next start boots the current one." }, "sshPublicKey": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "stoppedAt": { "type": [ "string", "null" ], "format": "date-time" }, "title": { "type": "string", "description": "What people call the workspace (1–200 characters)." }, "updatedAt": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int64", "description": "Settings revision; send it back with a settings change." } } }, "WorkspaceId": { "type": "string" }, "WorkspaceLaunchDto": { "type": "object", "description": "The delivery of a workspace's first message (`initialPrompt`). Every change is a `workspace` entity event.", "required": [ "chatId", "status", "createdAt", "updatedAt" ], "properties": { "chatId": { "type": "string", "format": "uuid", "description": "The runtime chat the message goes to, chosen when the workspace is created: open it straight away. It\nanswers 404 until the launch delivers the message." }, "createdAt": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ], "description": "Why the launch failed, was cancelled or interrupted, in words for people." }, "prompt": { "type": [ "string", "null" ], "description": "The message while it has not reached the chat (`pending`, or `failed`/`cancelled` before delivery), to show\nas the pending first message or to send by hand." }, "status": { "$ref": "#/components/schemas/LaunchStatus" }, "turnId": { "type": [ "string", "null" ], "format": "uuid", "description": "The first turn, once the runtime accepted the message." }, "updatedAt": { "type": "string", "format": "date-time" } } }, "WorkspaceOperationResponse": { "type": "object", "description": "`POST /api/v1/workspaces` → 202 `{\"workspace\":{…,\"observedState\":\"created\",\"desiredState\":\"running\"},\"operation\":{\"id\":\"…\",\"kind\":\"create\",\"status\":\"queued\",…}}`", "required": [ "workspace", "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/OperationDto" }, "workspace": { "$ref": "#/components/schemas/WorkspaceDto" } } }, "WorkspaceOptionsResponse": { "type": "object", "required": [ "regions", "defaultRegion", "resourceClasses", "defaultResourceClass", "defaultDiskGb", "maxDiskGb", "defaultIdleTimeoutSecs", "exportsAvailable" ], "properties": { "defaultDiskGb": { "type": "integer", "format": "int64" }, "defaultIdleTimeoutSecs": { "type": "integer", "format": "int64", "minimum": 0 }, "defaultRegion": { "type": "string" }, "defaultResourceClass": { "$ref": "#/components/schemas/ResourceClass" }, "exportsAvailable": { "type": "boolean", "description": "Whether `POST /api/v1/workspaces/{id}/export` can produce a downloadable archive on this deployment." }, "maxDiskGb": { "type": "integer", "format": "int64", "description": "500" }, "regions": { "type": "array", "items": { "type": "string" } }, "resourceClasses": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceClass" } } } }, "WorkspaceSkill": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "object", "description": "UTF-8 files relative to this skill directory; must include SKILL.md.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } }, "additionalProperties": false }, "WorkspaceState": { "type": "string", "enum": [ "created", "provisioning", "starting", "running", "stopping", "stopped", "failed", "deleting", "deleted" ] }, "WorkspaceTemplate": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "empty" ] } } }, { "type": "object", "required": [ "url", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "git" ] }, "ref": { "type": [ "string", "null" ] }, "url": { "type": "string" } } } ] } } }, "tags": [ { "name": "remote", "description": "Connected computers and explicitly published local chats" }, { "name": "attention", "description": "Pending requests and finished chats on computers and Cloud workspaces" }, { "name": "push", "description": "Push notifications and live chat updates for the phone apps (iOS and Android)" }, { "name": "cloud-schedules", "description": "Durable Cloud prompts targeting workspace chats" }, { "name": "cloud-agents", "description": "Reusable agent templates for Cloud workspaces" }, { "name": "identity", "description": "Login, sessions, devices, native OAuth and the device flow" }, { "name": "accounts", "description": "Accounts, members and projects" }, { "name": "workspaces", "description": "Workspaces, attach tickets, snapshots, exports and operations" }, { "name": "billing", "description": "Plans, checkout, wallet, usage, ledger, budgets and payments" }, { "name": "routers", "description": "Account router configurations and provider credentials" }, { "name": "router-keys", "description": "Managed router keys and model prices" }, { "name": "marketplace", "description": "Resources, collections, publishers and submissions" }, { "name": "releases", "description": "Release manifests" }, { "name": "profiles", "description": "Profile archives" }, { "name": "telemetry", "description": "Usage statistics of the desktop and CLI apps" }, { "name": "reports", "description": "Reports of an agent's reply, sent from the Haarness apps" }, { "name": "internal", "description": "Internal ops and fixtures-only test endpoints" }, { "name": "meta", "description": "Health, readiness, capabilities, this document and the phone apps' link files" } ] }