{ "openapi": "3.1.0", "info": { "title": "plori REST API", "version": "1.0.0", "summary": "Create agents and Workspaces, run agents, and inspect saved resources.", "description": "Candidate Workspace REST surface and established Agent API. Workspace access is cohort gated; Files routes have a separate gate. This source contract does not claim a production rollout. Use the operation status and saved revision to distinguish queued work, saved data, and accepted root state.", "contact": { "name": "plori", "url": "https://plori.ai", "email": "agent@plori.ai" }, "termsOfService": "https://plori.ai/terms" }, "servers": [ { "url": "https://api.plori.ai" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/agents": { "post": { "operationId": "createAgent", "summary": "Create an agent (or get-or-create by name)", "description": "Creates a cloud agent owned by the authenticated account. With `if_exists: \"return\"` this is get-or-create: if an agent with the same name exists, it is returned (200, `existing: true`) instead of creating a duplicate. Prefer this and one long-lived agent. The owner is always the credential's account; a `user_id` in the body is ignored.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "model": { "type": "string", "description": "Model slug; omit for the Plori Router default." }, "config": { "type": "object", "description": "Opaque agent config; defaults to {}." }, "if_exists": { "type": "string", "enum": [ "return", "error" ], "description": "\"return\" = get-or-create by name; \"error\" (default) = always create." }, "kind": { "type": "string", "enum": [ "compatibility", "independent" ], "description": "Independent identities run only as Workspace members. Omit for a compatibility Agent." } }, "if": { "properties": { "kind": { "const": "independent" } }, "required": [ "kind" ] }, "then": { "not": { "required": [ "if_exists" ] } } } } } }, "responses": { "201": { "description": "Agent created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "200": { "description": "Existing agent returned (get-or-create hit).", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Agent" }, { "type": "object", "properties": { "existing": { "type": "boolean" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Plan does not allow the requested model tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-plan agent cap reached. `Retry-After: 60`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Required with kind independent (nonempty, at most 255 bytes). For that kind, if_exists is forbidden." } ] }, "get": { "operationId": "listAgents", "summary": "List your agents", "responses": { "200": { "description": "The authenticated account's agents.", "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Agent" }, { "$ref": "#/components/schemas/AgentListEntry" } ], "description": "AgentListEntry is returned when include_independent=true; Agent is returned otherwise." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "name": "include_independent", "in": "query", "schema": { "type": "boolean" }, "description": "Include independent Agent identities and the kind, lifecycle_state, and workspace_storage fields; default false." } ] } }, "/v1/agents/{agentID}": { "get": { "operationId": "getAgent", "summary": "Get one agent", "parameters": [ { "$ref": "#/components/parameters/agentID" } ], "responses": { "200": { "description": "The agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agentID}/files/read": { "get": { "operationId": "readAgentFile", "summary": "Read one window of a text file on an agent's disk", "description": "Returns `text/plain` for a text file. This is the editor route: a file that is not text answers 415, and a file over the 2 MiB text cap answers 413 unless a window was asked for. Both refusals carry a `download_url` for the route that does serve those bytes. Use `offset` and `limit` to page through a file of any size; every 200 states what it covered in `X-File-Offset`, `X-File-Returned-Bytes`, `X-File-Size` and `X-File-Truncated`, so a short body is never silent. The disk is served directly, so an idle agent's files are readable with no running pod.", "parameters": [ { "$ref": "#/components/parameters/agentID" }, { "name": "path", "in": "query", "required": true, "description": "The file's path on the agent's disk, rooted at the disk root.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Byte offset of the first byte to return. Default 0.", "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "How many bytes to return, clamped to the 2 MiB per-call cap. Absent or 0 means the cap.", "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "The requested window of the file, as text.", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-File-Size": { "description": "Size of the whole file in bytes.", "schema": { "type": "integer", "format": "int64" } }, "X-File-Offset": { "description": "Byte offset this body starts at.", "schema": { "type": "integer", "format": "int64" } }, "X-File-Returned-Bytes": { "description": "How many bytes this body carries.", "schema": { "type": "integer", "format": "int64" } }, "X-File-Truncated": { "description": "true when bytes remain past this window.", "schema": { "type": "boolean" } }, "ETag": { "description": "The file's version, for a compare-and-swap write.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "description": "The file is over the text cap and no window was asked for. The body carries `size`, `cap` and `download_url`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "The file is not text. The body carries `download_url` for the route that streams its bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents/{agentID}/files/download": { "get": { "operationId": "downloadAgentFile", "summary": "Download one file from an agent's disk", "description": "Streams a file's bytes \u2014 text or binary, any size the account can hold \u2014 with its own content type for known extensions and `application/octet-stream` otherwise. This is the route a file link in an agent's reply resolves to. The disk is served directly, so an idle agent's files are downloadable with no running pod.", "parameters": [ { "$ref": "#/components/parameters/agentID" }, { "name": "path", "in": "query", "required": true, "description": "The file's path on the agent's disk, rooted at the disk root.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file's bytes. `Content-Disposition` is always an attachment, and `X-File-Size` carries the size the disk reported before the stream started.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-File-Size": { "description": "Size of the file in bytes, as of the stat that preceded the stream.", "schema": { "type": "integer", "format": "int64" } }, "ETag": { "description": "The file's version.", "schema": { "type": "string" } } } }, "400": { "description": "No path was given, or the path is a directory (`error: \"is a directory\"`) \u2014 list it instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agentID}/runs": { "post": { "operationId": "invokeAgent", "summary": "Send the agent a message (submit a run)", "description": "Submits a run and returns 202 immediately; there is no blocking or SSE mode on this endpoint. Read the reply over the session WebSocket (`GET /v1/ws`), poll `GET /v1/agents/{agentID}/runs/{runID}` for status, or use the MCP `send_workspace_message` tool, which can wait. A run is nondeterministic and billable. Retry only with an `Idempotency-Key`: the same key replays the original run for 24 h (the replay carries `X-Plori-Idempotent-Replay: true`).", "security": [ { "bearerAuth": [] }, { "githubRunAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/agentID" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional run deduplication key. If the nonempty header and JSON idempotency_key are both set, the header takes precedence." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The user message. Exactly one of `message` or `messages` is required; `messages` wins if both are set." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/UserInvokeMessage" } }, "session_id": { "type": "string", "description": "Continue an existing thread; omit to start a new one." }, "idempotency_key": { "type": "string", "maxLength": 255 }, "max_turn_tokens": { "type": "integer", "minimum": 0, "maximum": 5000000, "description": "Cap for this turn; 0 or omitted = the default budget." }, "max_advisor_spend_micro_usd": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 5000000, "description": "Advisor completion cap for the turn in micro-USD. Omit the field or send null to use the agent cap. Set 0 to disable advisor completions." }, "max_turn_seconds": { "type": "integer", "minimum": 0, "description": "Soft checkpoint for this turn; 0 or omitted = the default." }, "github_token": { "type": "string", "writeOnly": true, "description": "Job-lifetime contents:read GITHUB_TOKEN for repository checkout. Delivered only to this turn in memory and never persisted; the owning API-key fallback is supported for GHES." }, "github_server_url": { "type": "string", "format": "uri", "description": "HTTPS origin that issued github_token, such as https://github.com or a GHES origin. The token's in-memory Git credential helper is scoped to this host; invalid values fall back to github.com." }, "callback_url": { "type": "string" }, "callback_secret": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "Run submitted. Headers `X-Plori-Run-Id` and `X-Plori-Session-Id` mirror the body.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "session_id" ], "properties": { "run_id": { "type": "string" }, "session_id": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditExhaustion" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Agent or session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A request with this Idempotency-Key is still in flight. `Retry-After: 2`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "This Idempotency-Key was already used for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Plan concurrency cap or cluster capacity. `Retry-After: 10`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listAgentRuns", "summary": "List the agent's runs", "parameters": [ { "$ref": "#/components/parameters/agentID" } ], "responses": { "200": { "description": "Run history, newest first.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agentID}/runs/{runID}": { "get": { "operationId": "getAgentRun", "summary": "Get one run's status", "parameters": [ { "$ref": "#/components/parameters/agentID" }, { "$ref": "#/components/parameters/runID" } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agentID}/runs/{runID}/cancel": { "post": { "operationId": "cancelAgentRun", "summary": "Cancel an in-flight run", "description": "Requests cancellation; cascades to any child runs the run delegated to.", "parameters": [ { "$ref": "#/components/parameters/agentID" }, { "$ref": "#/components/parameters/runID" } ], "responses": { "202": { "description": "Cancellation requested.", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string" }, "status": { "type": "string", "const": "cancelling" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Run already finished.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agents/{agentID}/schedules": { "post": { "operationId": "createSchedule", "summary": "Schedule a deferred one-shot run", "description": "A direct owner session using the owner's plori_sk_ API key outside MCP creates a pending schedule. An MCP request or OAuth access token creates an awaiting_confirmation schedule with confirm_url. It cannot fire until the owner confirms. Unconfirmed rows have no expiry sweep.", "parameters": [{ "$ref": "#/components/parameters/agentID" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string" }, "fire_at": { "type": "string", "format": "date-time", "description": "RFC3339 UTC. Exactly one of `fire_at` or `delay_seconds`." }, "delay_seconds": { "type": "integer", "minimum": 0 }, "session_id": { "type": "string", "description": "Pin the thread; omit for the agent's active thread." }, "metadata": { "type": "object" } } } } } }, "responses": { "201": { "description": "Schedule created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "operationId": "listSchedules", "summary": "List the agent's schedules", "parameters": [ { "$ref": "#/components/parameters/agentID" } ], "responses": { "200": { "description": "Schedules.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Schedule" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agentID}/schedules/{scheduleID}": { "get": { "operationId": "getSchedule", "summary": "Get one schedule", "parameters": [ { "$ref": "#/components/parameters/agentID" }, { "$ref": "#/components/parameters/scheduleID" } ], "responses": { "200": { "description": "The schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "cancelSchedule", "summary": "Cancel an unconfirmed, pending, or dispatched schedule", "description": "Returns the updated schedule (200, not 204). A schedule that already fired is a 404 because there is nothing left to cancel.", "parameters": [ { "$ref": "#/components/parameters/agentID" }, { "$ref": "#/components/parameters/scheduleID" } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/users/{userID}/credits": { "get": { "operationId": "getCredits", "summary": "Get the account's credit balance and plan", "description": "`userID` must be the authenticated account's own id (anything else is 403). Check the balance before taking on long work.", "parameters": [ { "name": "userID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Balance, plan, and purchase options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agentID}/schedules/{scheduleID}/confirm": { "post": { "operationId": "confirmSchedule", "summary": "Confirm a deferred schedule as the account owner", "description": "Requires the owner's own plori_sk_ API key outside MCP. Takes no body. Changes awaiting_confirmation to pending and records confirmed_at only while fire_at is in the future. An already confirmed row returns 200 unchanged. MCP and OAuth requests receive 403 with the confirmation link in the error text.", "parameters": [{ "$ref": "#/components/parameters/agentID" }, { "$ref": "#/components/parameters/scheduleID" }], "responses": { "200": { "description": "Schedule confirmed, or already confirmed (idempotent).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Schedule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "AI clients cannot confirm; the error text includes the owner's confirmation link. Another account's agent is also forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agent or schedule not found, or schedule outside the addressed agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Unconfirmed fire time has passed, the row's state cannot be confirmed and confirmed_at is unset, or the agent is being deleted (code: agent_deleting).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/github/oidc/exchange": { "post": { "operationId": "exchangeGitHubOIDC", "summary": "Exchange GitHub Actions workload identity for one run", "description": "Verifies a GitHub Actions OIDC JWT minted for audience `plori.ai`, resolves the repository's persistent agent, and returns a short-lived single-run capability. Public repositories receive up to 3 free runs per repository and 10 per GitHub owner per UTC month while unclaimed. Private repositories and exhausted public repositories receive a claim URL instead. This endpoint never creates a customer account or API key.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "writeOnly": true, "description": "GitHub Actions OIDC JWT with audience plori.ai." } } } } } }, "responses": { "200": { "description": "Repository identity accepted; use this capability once on POST /v1/agents/{agentID}/runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubOIDCExchange" } } } }, "401": { "description": "OIDC signature, issuer, audience, lifetime, or repository claims are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Repository must be claimed before it can run. The body includes a signed claim URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubClaimRequired" } } } }, "409": { "description": "The repository agent is being provisioned. Retry after the indicated delay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/github/claim": { "post": { "operationId": "claimGitHubRepository", "summary": "Attach a verified repository to the signed-in account", "description": "Combines the signed repository claim capability from a workflow with a registered Plori payer identity. The same repository agent, disk, threads, and private memory move to that account. Safe to retry by the same account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "repository", "claim_token" ], "properties": { "repository": { "type": "string", "example": "owner/repository" }, "claim_token": { "type": "string", "writeOnly": true } } } } } }, "responses": { "200": { "description": "Repository attached or already attached to this account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "repository", "agent_id", "already_bound" ], "properties": { "repository": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "already_bound": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "A registered account is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Repository belongs to another account; contact support for a transfer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/github/runs/{runID}": { "get": { "operationId": "getGitHubRunResult", "summary": "Poll one GitHub-triggered run's durable event stream", "description": "Returns AG-UI events after `after_seq`. A GitHub capability is scoped to its repository agent; the manual API-key fallback can read only runs owned by that account.", "security": [ { "githubRunAuth": [] }, { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/runID" }, { "name": "after_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Current status and the next durable event page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "cause", "terminal", "after_seq", "events" ], "properties": { "run_id": { "type": "string" }, "status": { "type": "string" }, "cause": { "type": "string", "description": "Machine-readable terminal cause. Empty while the run is active and after normal completion.", "enum": [ "", "user_stop", "interrupted", "stalled", "time_limit", "credits_exhausted", "task_budget_exhausted", "backend_error", "spawn_failed", "workspace_copy_held", "account_disk_full", "agent_deleted" ] }, "terminal": { "type": "boolean" }, "after_seq": { "type": "integer" }, "events": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/pricing/models": { "get": { "operationId": "getModelPricing", "summary": "Public model rate card", "security": [], "responses": { "200": { "description": "Per-model token rates at the provider's real cost, no markup. Amounts are micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelPricing" } } } } } } }, "/v1/pricing/tools": { "get": { "operationId": "getToolPricing", "summary": "Public tool and workflow rate card", "security": [], "responses": { "200": { "description": "Per-tool rates and workflow run pricing, in micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolPricing" } } } } } } }, "/v1/workspaces": { "get": { "summary": "Get workspaces", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required nonempty key, at most 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "backend": { "type": "string" }, "model": { "type": "string" }, "config": { "type": "object" }, "default_manager_agent_id": { "type": "string", "format": "uuid" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/by-agent/{agentID}": { "get": { "summary": "Get workspaces by-agent agentID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "agentID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/workspaces/{workspaceID}": { "get": { "summary": "Get workspaces workspaceID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "summary": "Update workspaces workspaceID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "default_manager_agent_id": { "type": "string", "format": "uuid" }, "retention_profile": { "type": "string" }, "retention_version": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete or release workspaces workspaceID", "description": "Deletes a stored Workspace. This cleanup route remains available to its owner after the owner cohort is disabled.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "202": { "description": "Erasure requested. Physical purge is asynchronous.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workspace" } } } }, "204": { "description": "Workspace was already deleted." } } } }, "/v1/workspaces/{workspaceID}/storage/adopt": { "post": { "summary": "Create or start workspaces workspaceID storage adopt", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required nonempty key, at most 255 bytes." } ], "responses": { "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/storage/adoption": { "get": { "summary": "Get workspaces workspaceID storage adoption", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/workspaces/{workspaceID}/storage/adoption/cancel": { "post": { "summary": "Create or start workspaces workspaceID storage adoption cancel", "description": "Cancels a stopping storage adoption. This cleanup route remains available to its owner after the owner cohort is disabled.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/workspaces/{workspaceID}/storage/adoption/rollback": { "post": { "summary": "Roll back Workspace storage adoption", "description": "Returns an adopted Workspace to its legacy volume during the rollback window. Refuses rollback if the Workspace has changed or has active work. This route remains available to its owner after the owner cohort is disabled.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "The restored Workspace.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Workspace storage is unavailable. Retry after the delay in the Retry-After header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/members": { "get": { "summary": "Get workspaces workspaceID members", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces workspaceID members", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" } }, "required": [ "agent_id" ] } } } } } }, "/v1/workspaces/{workspaceID}/members/{memberID}": { "delete": { "summary": "Delete or release workspaces workspaceID members memberID", "description": "Revokes a Workspace member. This cleanup route remains available to its owner after the owner cohort is disabled.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "memberID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/workspaces/{workspaceID}/threads": { "get": { "summary": "Get workspaces workspaceID threads", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Thread DTO" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces workspaceID threads", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } } } } } } } }, "/v1/workspaces/{workspaceID}/runs": { "get": { "summary": "Get workspaces workspaceID runs", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Run DTO" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces workspaceID runs", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional run deduplication key. If the nonempty header and JSON idempotency_key are both set, the header takes precedence." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/UserInvokeMessage" } }, "session_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string" }, "executor_agent_id": { "type": "string", "format": "uuid" }, "context": { "type": "object" }, "max_turn_tokens": { "type": "integer" }, "max_turn_seconds": { "type": "integer" }, "max_advisor_spend_micro_usd": { "type": "integer" }, "callback_url": { "type": "string" }, "callback_secret": { "type": "string" }, "github_token": { "type": "string" }, "github_server_url": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "session_id" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/costs": { "get": { "summary": "Get workspaces workspaceID costs", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "resource_limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "resource_cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/workspaces/{workspaceID}/context-items": { "get": { "summary": "Get workspaces workspaceID context-items", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces workspaceID context-items", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "version": { "type": "integer" }, "content": { "type": "string" }, "provenance": { "type": "object" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." } }, "required": [ "label", "version", "content" ] } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "201": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/workspaces/{workspaceID}/context-items/{contextItemID}": { "delete": { "summary": "Delete or release workspaces workspaceID context-items contextItemID", "description": "Revokes a stored context item. This cleanup route remains available to the owner after the Workspace cohort is disabled.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "contextItemID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/workspaces/{workspaceID}/checkpoints": { "post": { "summary": "Create or start workspaces workspaceID checkpoints", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "working_copy_id": { "type": "string", "format": "uuid", "description": "Omit to save the root working copy." }, "scope": { "type": "string", "enum": [ "full" ], "description": "Only full file scope is supported." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." } } } } } }, "responses": { "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/copies": { "get": { "summary": "Get workspaces workspaceID copies", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "copies": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceCopy" } }, "next_cursor": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create or start workspaces workspaceID copies", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_revision": { "type": "string", "format": "uuid" }, "scope": { "type": "string", "enum": [ "full" ], "description": "Only full file scope is supported." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." } }, "required": [ "base_revision" ] } } } }, "responses": { "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}": { "get": { "summary": "Get workspaces workspaceID copies workingCopyID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCopy" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete or release workspaces workspaceID copies workingCopyID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperation" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "description": "Optional JSON body. Send idempotency_key here when the Idempotency-Key header is absent. A nonempty header takes precedence. working_copy_id and base_revision must be absent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if the header is absent." }, "scope": { "type": "string", "enum": [ "full" ] } } } } } } } }, "/v1/workspaces/{workspaceID}/revisions": { "get": { "summary": "Get workspaces workspaceID revisions", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceRevision" } }, "next_cursor": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/revisions/{revisionID}": { "get": { "summary": "Get workspaces workspaceID revisions revisionID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceRevision" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete or release workspaces workspaceID revisions revisionID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperation" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "description": "Optional JSON body. Send idempotency_key here when the Idempotency-Key header is absent. A nonempty header takes precedence. working_copy_id and base_revision must be absent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if the header is absent." }, "scope": { "type": "string", "enum": [ "full" ] } } } } } } } }, "/v1/workspaces/{workspaceID}/operations/{operationID}": { "get": { "summary": "Get workspaces workspaceID operations operationID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operationID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOperation" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/retention": { "get": { "summary": "Get workspaces workspaceID retention", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "view", "in": "query", "schema": { "type": "string", "enum": [ "cleanup", "pins" ], "default": "cleanup" }, "description": "Defaults to cleanup." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Exclusive cursor from next_cursor." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceRetentionView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/retention/pins": { "post": { "summary": "Create or start workspaces workspaceID retention pins", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Required nonempty key, at most 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_kind": { "type": "string" }, "resource_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "resource_kind", "resource_id", "expires_at" ] } } } }, "responses": { "201": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceRetentionPin" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/retention/pins/{pinID}": { "delete": { "summary": "Delete or release workspaces workspaceID retention pins pinID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "pinID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Request accepted or completed." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/review-actions/{actionID}": { "get": { "summary": "Get workspaces workspaceID review-actions actionID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "actionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/changesets": { "get": { "summary": "Get workspaces workspaceID changesets", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create or start workspaces workspaceID changesets", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_revision": { "type": "string", "format": "uuid" }, "incoming_revision": { "type": "string", "format": "uuid" }, "expected_current_revision": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." }, "incoming_save_operation_id": { "type": "string", "format": "uuid", "description": "Save operation for the selected proposal. Preserve this ID when the proposal reuses a revision and when repeating a comparison." } }, "required": [ "base_revision", "incoming_revision", "expected_current_revision" ] } } } }, "responses": { "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceChangeset" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/changesets/{changesetID}": { "get": { "summary": "Get workspaces workspaceID changesets changesetID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "changesetID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceChangeset" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/changesets/{changesetID}/reject": { "post": { "summary": "Create or start workspaces workspaceID changesets changesetID reject", "description": "Rejects a changeset. This cleanup route remains available to its owner after the owner cohort is disabled.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "changesetID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." } } } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceChangeset" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/changesets/{changesetID}/accept": { "post": { "summary": "Create or start workspaces workspaceID changesets changesetID accept", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "changesetID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_current_revision": { "type": "string", "format": "uuid" }, "validation_evidence": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Nonblank evidence, at most 2048 UTF-8 bytes." }, "minItems": 1, "maxItems": 32 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." } }, "required": [ "expected_current_revision", "validation_evidence" ] } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceChangeset" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/changesets/{changesetID}/resolve": { "post": { "summary": "Create or start workspaces workspaceID changesets changesetID resolve", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "changesetID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_write_generation": { "type": "integer" }, "resolutions": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceChangesetResolution" } }, "validation_evidence": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Nonblank evidence, at most 2048 UTF-8 bytes." }, "minItems": 1, "maxItems": 32 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." } }, "required": [ "expected_write_generation", "resolutions", "validation_evidence" ] } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceChangeset" } } } }, "422": { "description": "The idempotency key was reused for a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/revisions/{revisionID}/files/list": { "get": { "summary": "Get workspaces workspaceID revisions revisionID files list", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Next page cursor returned by a storage-worker list." } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/revisions/{revisionID}/files/stat": { "get": { "summary": "Get workspaces workspaceID revisions revisionID files stat", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/revisions/{revisionID}/files/read": { "get": { "summary": "Get workspaces workspaceID revisions revisionID files read", "description": "Reads the entire retained revision file as text. Files above the editor cap return 413; offset and limit are not supported.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Text bytes. Binary and over-cap files are refused; use download.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "413": { "description": "Text file exceeds the editor cap." }, "415": { "description": "The file is binary." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/revisions/{revisionID}/files/download": { "get": { "summary": "Get workspaces workspaceID revisions revisionID files download", "description": "Streams the entire selected file to the authenticated owner. Offset and limit are not supported.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "revisionID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/list": { "get": { "summary": "Get workspaces workspaceID copies workingCopyID files list", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Next page cursor returned by a storage-worker list." } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/stat": { "get": { "summary": "Get workspaces workspaceID copies workingCopyID files stat", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/read": { "get": { "summary": "Get workspaces workspaceID copies workingCopyID files read", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Zero requests the maximum read window, not an empty response." } ], "responses": { "200": { "description": "Text bytes. Binary and over-cap files are refused; use download.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "413": { "description": "Text file exceeds the editor cap." }, "415": { "description": "The file is binary." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/download": { "get": { "summary": "Get workspaces workspaceID copies workingCopyID files download", "description": "Streams the entire selected file to the authenticated owner. Offset and limit are not supported.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/write": { "put": { "summary": "Set or write workspaces workspaceID copies workingCopyID files write", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Path inside the selected Workspace file tree." }, { "name": "If-Match", "in": "header", "schema": { "type": "string" }, "description": "Expected ETag for compare-and-swap. Without it, only creation at version zero succeeds." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The current ETag does not match." } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/upload": { "post": { "summary": "Create or start workspaces workspaceID copies workingCopyID files upload", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Destination directory; omit for the root." }, { "name": "name", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "overwrite", "in": "query", "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "size", "etag" ], "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "etag": { "type": "string", "pattern": "^[0-9]+$" } } } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/delete": { "post": { "summary": "Create or start workspaces workspaceID copies workingCopyID files delete", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Path inside the selected Workspace file tree." } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "trash" ], "properties": { "trash": { "type": "string" } } } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/restore": { "post": { "summary": "Create or start workspaces workspaceID copies workingCopyID files restore", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Trash handle returned by Files delete, not the original file path." } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/empty-trash": { "post": { "summary": "Create or start workspaces workspaceID copies workingCopyID files empty-trash", "description": "Purges all trash in the selected Workspace copy. There is no path filter.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer" } } } } } } } } }, "/v1/workspaces/{workspaceID}/copies/{workingCopyID}/files/download-url": { "post": { "summary": "Create or start workspaces workspaceID copies workingCopyID files download-url", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workingCopyID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Path inside the selected Workspace file tree." }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "preview" ] } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "503": { "description": "Workspace storage is starting or unavailable; inspect Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/list": { "get": { "summary": "Get workspaces workspaceID files list", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Next page cursor returned by a storage-worker list." } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/stat": { "get": { "summary": "Get workspaces workspaceID files stat", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/read": { "get": { "summary": "Get workspaces workspaceID files read", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "Zero requests the maximum read window, not an empty response." } ], "responses": { "200": { "description": "Text bytes. Binary and over-cap files are refused; use download.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "413": { "description": "Text file exceeds the editor cap." }, "415": { "description": "The file is binary." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/download": { "get": { "summary": "Get workspaces workspaceID files download", "description": "Streams the entire selected file to the authenticated owner. Offset and limit are not supported.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/write": { "put": { "summary": "Set or write workspaces workspaceID files write", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Path inside the selected Workspace file tree." }, { "name": "If-Match", "in": "header", "schema": { "type": "string" }, "description": "Expected ETag for compare-and-swap. Without it, only creation at version zero succeeds." } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "The current ETag does not match." } } } }, "/v1/workspaces/{workspaceID}/files/upload": { "post": { "summary": "Create or start workspaces workspaceID files upload", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Destination directory; omit for the root." }, { "name": "name", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "overwrite", "in": "query", "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "size", "etag" ], "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "etag": { "type": "string", "pattern": "^[0-9]+$" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/delete": { "post": { "summary": "Create or start workspaces workspaceID files delete", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Path inside the selected Workspace file tree." } ], "responses": { "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "trash" ], "properties": { "trash": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/restore": { "post": { "summary": "Create or start workspaces workspaceID files restore", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Trash handle returned by Files delete, not the original file path." } ], "responses": { "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/empty-trash": { "post": { "summary": "Create or start workspaces workspaceID files empty-trash", "description": "Purges all trash in the selected Workspace copy. There is no path filter.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "Conflict, active operation, or current-revision mismatch. A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/files/download-url": { "post": { "summary": "Create or start workspaces workspaceID files download-url", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable. Files mutations use the selected copy; a write is distinct from saving a revision.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Path inside the selected Workspace file tree." }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "preview" ] } } ], "responses": { "200": { "description": "Files request completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound", "description": "The resource is not found, or the Workspace is deleted (code: workspace_deleted)." }, "409": { "description": "A deleting Workspace returns code workspace_deleting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/workers": { "get": { "summary": "Get workspaces workspaceID workers", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "task_group_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceWorker" } }, "next_cursor": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces workspaceID workers", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "working_copy_id": { "type": "string", "format": "uuid" }, "task_group_id": { "type": "string", "format": "uuid" }, "task": { "type": "string" }, "executor_agent_id": { "type": "string", "format": "uuid" }, "session_id": { "type": "string" }, "name": { "type": "string" }, "backend": { "type": "string" }, "model": { "type": "string" }, "config": { "type": "object" }, "context_selection": { "type": "object" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." }, "callback_url": { "type": "string" }, "callback_secret": { "type": "string" } }, "required": [ "working_copy_id", "task_group_id", "task" ] } } } }, "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWorker" } } } } } } }, "/v1/workspaces/{workspaceID}/workers/{workerRequestID}": { "get": { "summary": "Get workspaces workspaceID workers workerRequestID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workerRequestID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWorker" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/workspaces/{workspaceID}/task-groups": { "get": { "summary": "Get workspaces workspaceID task-groups", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceTaskGroup" } }, "next_cursor": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces workspaceID task-groups", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Provide this header or the JSON idempotency_key field. The nonempty header takes precedence when both are set; maximum 255 bytes." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "limit_cache_weighted_tokens": { "type": "integer" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Required if Idempotency-Key header is absent. Nonempty header takes precedence." } }, "required": [ "limit_cache_weighted_tokens" ] } } } }, "responses": { "201": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTaskGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/task-groups/{taskGroupID}": { "get": { "summary": "Get task-groups taskGroupID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "taskGroupID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTaskGroup" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/task-groups/{taskGroupID}/costs": { "get": { "summary": "Get task-groups taskGroupID costs", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "taskGroupID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "resource_limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "resource_cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/task-groups/{taskGroupID}/stop": { "post": { "summary": "Create or start task-groups taskGroupID stop", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "taskGroupID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "See the response body and resource state; asynchronous work requires polling.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/site": { "get": { "summary": "Get workspaces workspaceID site", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "summary": "Set or write workspaces workspaceID site", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "root_path": { "type": "string" }, "published": { "type": "boolean" }, "visibility": { "type": "string" }, "kind": { "type": "string", "enum": [ "static", "service" ] } } } } } } } }, "/v1/workspaces/{workspaceID}/site/open": { "post": { "summary": "Create or start workspaces workspaceID site open", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/inbound-email": { "get": { "summary": "Get workspaces workspaceID inbound-email", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/workspaces/{workspaceID}/schedules": { "get": { "summary": "Get workspaces workspaceID schedules", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Schedule DTO" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or start workspaces workspaceID schedules", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string" }, "fire_at": { "type": "string", "format": "date-time" }, "delay_seconds": { "type": "integer" }, "session_id": { "type": "string", "format": "uuid" }, "metadata": { "type": "object" }, "executor_agent_id": { "type": "string", "format": "uuid" } }, "required": [ "prompt" ] } } } }, "responses": { "201": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/workspaces/{workspaceID}/schedules/{scheduleID}": { "get": { "summary": "Get workspaces workspaceID schedules scheduleID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete or release workspaces workspaceID schedules scheduleID", "description": "Cancels a stored Workspace schedule. This cleanup route remains available to the owner after the Workspace cohort is disabled. Ownership, canonical-storage, and deleting-state checks still apply.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "scheduleID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/workspaces/{workspaceID}/workflows": { "get": { "summary": "Get workspaces workspaceID workflows", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/workspaces/{workspaceID}/workflows/{workflowID}": { "put": { "summary": "Set or write workspaces workspaceID workflows workflowID", "description": "Candidate Workspace API. Access depends on the owner cohort and, for Files routes, the Files gate. Check operation state and retained data before assuming a write is durable.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workflowID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request accepted or completed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete or release workspaces workspaceID workflows workflowID", "description": "Detaches a stored Workspace workflow. This cleanup route remains outside the Workspace admission gate after the cohort is disabled. The workflows feature gate and ownership, canonical-storage, and deleting-state checks still apply.", "parameters": [ { "name": "workspaceID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workflowID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "204": { "description": "Request accepted or completed." } } } }, "/v1/agents/{agentID}/stop": { "post": { "summary": "Create or start agents agentID stop", "description": "Cancels nonterminal runs. The agent can run again; memberships and Workspaces remain.", "parameters": [ { "name": "agentID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Agent lifecycle result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentStop" } } } } } } }, "/v1/agents/{agentID}/retire": { "post": { "summary": "Create or start agents agentID retire", "description": "Retires the agent, requests cancellation of nonterminal runs, and detaches memberships. Workspace, thread, and run history remain. An agent that is a Workspace's default manager is refused with 409 workspace_manager_in_use and the Workspaces in workspace_ids; select another manager for each first.", "parameters": [ { "name": "agentID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Conflict, active operation, or current-revision mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Agent lifecycle result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRetire" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A plori API key (plori_sk_\u2026) or an OAuth 2.1 access token. How to get either: https://plori.ai/auth.md" }, "githubRunAuth": { "type": "http", "scheme": "bearer", "description": "A short-lived `plori_ghr_` capability returned only by the GitHub OIDC exchange. It submits exactly one run to one repository agent and polls only that run." } }, "parameters": { "agentID": { "name": "agentID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "runID": { "name": "runID", "in": "path", "required": true, "schema": { "type": "string" } }, "scheduleID": { "name": "scheduleID", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } }, "responses": { "BadRequest": { "description": "Malformed request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The resource belongs to another account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "request_id": { "type": "string", "description": "Present on 500 responses, whose error message is always the fixed string \"internal error\": quote this id to support to locate the failure." } } }, "CreditExhaustion": { "type": "object", "required": [ "error", "code", "audience" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "insufficient_credits" }, "audience": { "type": "string", "enum": [ "anon", "registered_free", "subscribed" ] } } }, "GitHubOIDCExchange": { "type": "object", "required": [ "token", "agent_id", "repository", "expires_at", "free_tier", "repo_runs_remaining", "owner_runs_remaining", "claim_url" ], "properties": { "token": { "type": "string", "writeOnly": true }, "agent_id": { "type": "string", "format": "uuid" }, "repository": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "free_tier": { "type": "boolean" }, "repo_runs_remaining": { "type": "integer", "minimum": 0 }, "owner_runs_remaining": { "type": "integer", "minimum": 0 }, "claim_url": { "type": "string", "format": "uri" } } }, "GitHubClaimRequired": { "type": "object", "required": [ "error", "code", "claim_url", "repository" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "github_repo_claim_required" }, "claim_url": { "type": "string", "format": "uri" }, "repository": { "type": "string" } } }, "AgentListEntry": { "allOf": [ { "$ref": "#/components/schemas/Agent" }, { "type": "object", "required": ["kind", "lifecycle_state", "workspace_storage"], "properties": { "kind": { "type": "string" }, "lifecycle_state": { "type": "string" }, "workspace_storage": { "type": "boolean", "description": "True when this agent is the canonical storage agent of a Workspace whose files are in Workspace storage, not in this agent's own volume. Such an agent cannot be selected as a new Workspace manager; a Workspace may retain its current manager." } } } ] }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "backend": { "type": "string" }, "model": { "type": "string" }, "config": { "type": "object" }, "entity_disk_id": { "type": "string" }, "status": { "type": "string", "description": "Warm-session state when known: warming, ready, or sleeping." }, "deleting": { "type": "boolean", "description": "True while this agent's disk is still being erased. The agent offers no actions except deletion itself, which is idempotent and the only way to finish a stuck one." }, "deleting_since": { "type": [ "string", "null" ], "format": "date-time", "description": "When the erasure was first asked for. Absent when the agent is not being deleted." }, "moving": { "type": "boolean", "description": "True while this agent's files are being copied to a new disk. Poll the migration progress route only while this is true." }, "created_at": { "type": "string", "format": "date-time" } } }, "UserInvokeMessage": { "type": "object", "additionalProperties": false, "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user" ] }, "content": { "type": "string" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/UserInvokePart" } } } }, "UserInvokePart": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "image", "text", "pdf" ] }, "path": { "type": "string" }, "mime": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "w": { "type": "integer" }, "h": { "type": "integer" } } }, "Message": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string" }, "content": { "type": "string" }, "tool_call_id": { "type": "string" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/Part" } } } }, "Part": { "type": "object", "properties": { "type": { "type": "string" }, "path": { "type": "string" }, "mime": { "type": "string" }, "w": { "type": "integer" }, "h": { "type": "integer" } } }, "Run": { "type": "object", "description": "Run status and accounting. The run's OUTPUT is not in this DTO. Read it over the session WebSocket or the MCP get_run_result tool.", "properties": { "id": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "thread_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "origin": { "type": "string", "enum": [ "user", "schedule", "background", "agent", "agent_result" ] }, "parent_run_id": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" }, "last_heartbeat_at": { "type": "string", "format": "date-time" }, "cause": { "type": "string", "enum": [ "user_stop", "workspace_stop", "credits_exhausted", "task_budget_exhausted", "workspace_save_refused", "interrupted", "stalled", "time_limit", "backend_error", "spawn_failed", "workspace_copy_held", "account_disk_full", "agent_deleted" ] }, "retryable": { "type": "boolean" }, "credits": { "type": [ "integer", "null" ], "description": "Amount charged for the run, in micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1." }, "tokens": { "type": [ "integer", "null" ] }, "stop_reason": { "type": "string" } } }, "Schedule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "const": "once" }, "status": { "type": "string", "enum": ["awaiting_confirmation", "pending", "firing", "dispatched", "done", "cancelled", "failed"], "description": "AI-client-created schedules await owner confirmation. done does not establish task success; inspect the run outcome." }, "prompt": { "type": "string" }, "fire_at": { "type": "string", "format": "date-time" }, "thread_id": { "type": "string" }, "metadata": { "type": "object" }, "last_error": { "type": "string" }, "attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "last_fired_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": "string", "format": "date-time", "description": "Time the owner confirmed the schedule. Absent when unset." }, "confirm_url": { "type": "string", "format": "uri", "description": "Owner confirmation page. Present only for awaiting_confirmation schedules." } } }, "Credits": { "type": "object", "properties": { "balance": { "type": "integer", "description": "Wallet balance in micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1. The wallet keeps the name 'credits' but every amount is US dollars." }, "low_credit_threshold": { "type": "integer", "description": "Low-balance threshold, in micro-USD (\u00b5$)." }, "peg_cents": { "type": "integer", "description": "Deprecated. Amounts are micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1; use that conversion rather than a credits-per-dollar rate." }, "packs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "usd_cents": { "type": "integer", "description": "Purchase price in whole US cents." }, "credits": { "type": "integer", "description": "Balance granted, in micro-USD (\u00b5$). Packs are flat: the \u00b5$ granted equals usd_cents \u00d7 10,000." } } } }, "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "usd_cents": { "type": "integer", "description": "Monthly price in whole US cents." }, "monthly_credits": { "type": "integer", "description": "Monthly usage allowance, in micro-USD (\u00b5$)." } } } }, "active_plan": { "type": [ "object", "null" ], "properties": { "sku": { "type": "string" }, "monthly_credits": { "type": "integer", "description": "Monthly usage allowance, in micro-USD (\u00b5$)." }, "status": { "type": "string" }, "current_period_end": { "type": "string", "format": "date-time" }, "cancel_at_period_end": { "type": "boolean" } } }, "can_manage_billing": { "type": "boolean" }, "audience": { "type": "string", "enum": [ "anon", "registered_free", "subscribed" ] } } }, "ModelPricing": { "type": "object", "properties": { "credits_per_usd": { "type": "integer", "description": "Deprecated. Amounts are micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1." }, "peg_cents": { "type": "integer", "description": "Deprecated. Amounts are micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1." }, "note": { "type": "string" }, "model_tiers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "in_nano_usd_per_tok": { "type": "integer" }, "out_nano_usd_per_tok": { "type": "integer" }, "credits_per_1k_in": { "type": "number" }, "credits_per_1k_out": { "type": "number" }, "free_tier_eligible": { "type": "boolean" } } } }, "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "in_nano_usd_per_tok": { "type": "integer" }, "out_nano_usd_per_tok": { "type": "integer" }, "free_tier_eligible": { "type": "boolean" } } } }, "free_max_model_out_nano_usd_per_tok": { "type": "integer" } } }, "ToolPricing": { "type": "object", "properties": { "peg_cents": { "type": "integer", "description": "Deprecated. Amounts are micro-USD (\u00b5$), where 1,000,000 \u00b5$ = $1." }, "tools": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string" }, "mode": { "type": "string", "enum": [ "free", "per_call" ] }, "credits": { "type": "integer", "description": "Per-call rate, in micro-USD (\u00b5$)." }, "free_per_month": { "type": "integer" }, "note": { "type": "string" } } } }, "allowance_reset": { "type": "string" }, "workflow": { "type": "object", "properties": { "exec_credits": { "type": "integer", "description": "Flat cost of a workflow run, in micro-USD (\u00b5$)." }, "included_seconds": { "type": "integer" }, "long_run_credits_per_minute": { "type": "integer", "description": "Per additional started minute past the included seconds, in micro-USD (\u00b5$)." }, "note": { "type": "string" } } } } }, "Workspace": { "type": "object", "required": [ "id", "owner_user_id", "name", "state", "canonical_storage_agent_id", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "state": { "type": "string", "enum": [ "adopting", "active", "deleting", "deleted" ] }, "legacy_agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "canonical_storage_agent_id": { "type": "string", "format": "uuid" }, "default_manager_agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "main_thread_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_revision": { "type": [ "string", "null" ], "format": "uuid" }, "root_working_copy_id": { "type": [ "string", "null" ], "format": "uuid" }, "retention_policy": { "type": "object" }, "storage_readiness": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WorkspaceWorker": { "type": "object", "required": [ "request_id", "workspace_id", "agent_id", "working_copy_id", "task_group_id", "status", "save_state", "reply_state" ], "properties": { "request_id": { "type": "string" }, "workspace_id": { "type": "string" }, "agent_id": { "type": "string" }, "working_copy_id": { "type": "string" }, "task_group_id": { "type": "string" }, "status": { "type": "string" }, "save_state": { "type": "string" }, "reply_state": { "type": "string" }, "change_status": { "type": "string" }, "base_revision": { "type": "string" }, "command_id": { "type": "string" }, "session_id": { "type": "string" }, "cause": { "type": "string", "description": "Terminal run cause, including task_budget_exhausted when the task group could not reserve the next model call." }, "saved_revision_id": { "type": [ "string", "null" ], "format": "uuid" }, "run_id": { "type": [ "string", "null" ], "format": "uuid" }, "changeset_id": { "type": [ "string", "null" ], "format": "uuid" }, "wait_for_reply": { "type": "boolean" }, "saved_operation_id": { "type": "string", "format": "uuid", "description": "Save operation for this worker run, including when it reuses a revision." } } }, "WorkspaceTaskGroup": { "type": "object", "required": [ "id", "workspace_id", "state", "limit_cache_weighted_tokens" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "state": { "type": "string" }, "limit_cache_weighted_tokens": { "type": "integer" }, "reserved_cache_weighted_tokens": { "type": "integer" }, "settled_cache_weighted_tokens": { "type": "integer" }, "budget_state": { "type": "string" } } }, "WorkspaceOperation": { "type": "object", "required": [ "id", "workspace_id", "kind", "state", "working_copy_id", "scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "state": { "type": "string" }, "working_copy_id": { "type": "string", "format": "uuid" }, "revision_id": { "type": "string", "format": "uuid" }, "base_revision": { "type": "string", "format": "uuid" }, "scope": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "code": { "type": "string" }, "retryable": { "type": "boolean" }, "attempt": { "type": "integer" }, "next_attempt_at": { "type": "string", "format": "date-time" }, "storage_status": { "type": "object" } } }, "WorkspaceCopy": { "type": "object", "required": [ "id", "workspace_id", "kind", "state", "base_revision", "scope", "files_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "state": { "type": "string" }, "base_revision": { "type": "string", "format": "uuid" }, "saved_revision": { "type": "string", "format": "uuid" }, "assigned_run_id": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string" }, "files_url": { "type": "string" }, "base_content": { "type": "object" }, "saved_content": { "type": "object" }, "mutable_content": { "type": "string" }, "retention_policy": { "type": "object" } } }, "WorkspaceRevision": { "type": "object", "required": [ "id", "workspace_id", "state", "source_working_copy_id", "scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "state": { "type": "string" }, "source_working_copy_id": { "type": "string", "format": "uuid" }, "base_revision": { "type": "string", "format": "uuid" }, "operation_id": { "type": "string", "format": "uuid" }, "scope": { "type": "string" }, "saved_content": { "type": "object" }, "retention_policy": { "type": "object" } } }, "WorkspaceChangeset": { "type": "object", "required": [ "id", "workspace_id", "state", "phase", "source_working_copy_id", "base_revision", "incoming_revision", "requested_expected_revision", "integration_write_generation", "root_write_generation" ], "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "state": { "type": "string" }, "phase": { "type": "string" }, "source_working_copy_id": { "type": "string", "format": "uuid" }, "base_revision": { "type": "string", "format": "uuid" }, "incoming_revision": { "type": "string", "format": "uuid" }, "requested_expected_revision": { "type": "string", "format": "uuid" }, "comparison_current_revision": { "type": "string", "format": "uuid" }, "result_revision": { "type": "string", "format": "uuid" }, "integration_working_copy_id": { "type": "string", "format": "uuid" }, "validation_evidence": { "type": "array", "items": { "type": "string" } }, "comparison": { "$ref": "#/components/schemas/WorkspaceChangesetComparison" }, "integration_write_generation": { "type": "integer", "format": "int64" }, "root_write_generation": { "type": "integer", "format": "int64" }, "resolution": { "$ref": "#/components/schemas/WorkspaceChangesetResolveRecord" }, "incoming_save_operation_id": { "type": "string", "format": "uuid", "description": "Save operation for the selected proposal." } } }, "WorkspaceRetentionPin": { "type": "object", "required": [ "id", "resource_kind", "resource_id", "expires_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "owner_user_id": { "type": "string", "format": "uuid" }, "resource_kind": { "type": "string" }, "resource_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "released_at": { "type": "string", "format": "date-time" } } }, "WorkspaceRetentionView": { "type": "object", "required": [ "policy", "storage_limits", "pins", "cleanup", "view", "counts" ], "properties": { "policy": { "type": "object" }, "storage_limits": { "type": [ "object", "null" ] }, "pins": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceRetentionPin" } }, "cleanup": { "type": "array", "items": { "type": "object" } }, "next_cursor": { "type": "string" }, "view": { "type": "string", "enum": [ "cleanup", "pins" ] }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "WorkspaceChangesetResolution": { "type": "object", "required": [ "path", "summary" ], "properties": { "path": { "type": "string" }, "expected_etag": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } ], "description": "Unsigned 64-bit etag. Canonical decimal string is accepted to preserve values beyond JavaScript integer precision." }, "deleted": { "type": "boolean" }, "summary": { "type": "string" }, "retained_variants": { "type": "array", "items": { "type": "string" } } }, "oneOf": [ { "required": [ "expected_etag" ], "properties": { "expected_etag": { "oneOf": [ { "type": "integer", "minimum": 1 }, { "type": "string", "pattern": "^[1-9][0-9]*$" } ] }, "deleted": { "const": false } } }, { "required": [ "deleted" ], "properties": { "deleted": { "const": true }, "expected_etag": { "enum": [ 0, "0" ] } } } ], "description": "Exactly one outcome: a positive expected_etag with deleted false, or deleted true with expected_etag absent or zero." }, "AgentRunStop": { "type": "object", "required": [ "run_id", "state" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "cancelling", "finished", "input_cancelled" ] } } }, "AgentStop": { "type": "object", "required": [ "agent_id", "kind", "lifecycle_state", "runs" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "lifecycle_state": { "type": "string" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRunStop" } } } }, "AgentRetire": { "allOf": [ { "$ref": "#/components/schemas/AgentStop" }, { "type": "object", "required": [ "detached_workspace_ids" ], "properties": { "detached_workspace_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } ] }, "WorkspaceChangesetComparison": { "type": "object", "required": [ "changeset_id", "integration_copy_id", "changes", "conflicts", "integration_tree_sha256", "no_change" ], "properties": { "changeset_id": { "type": "string", "format": "uuid" }, "integration_copy_id": { "type": "string", "format": "uuid" }, "changes": { "type": "array", "items": { "type": "object", "required": [ "path", "kind" ], "properties": { "path": { "type": "string" }, "kind": { "type": "string" }, "from": { "type": "string" } } } }, "conflicts": { "type": "array", "items": { "type": "object", "required": [ "path", "kind", "base", "current", "incoming" ], "properties": { "path": { "type": "string" }, "kind": { "type": "string" }, "base": { "$ref": "#/components/schemas/WorkspaceChangesetVariant" }, "current": { "$ref": "#/components/schemas/WorkspaceChangesetVariant" }, "incoming": { "$ref": "#/components/schemas/WorkspaceChangesetVariant" } } } }, "integration_tree_sha256": { "type": "string" }, "no_change": { "type": "boolean" } } }, "WorkspaceChangesetVariant": { "type": "object", "required": [ "revision_id", "path", "kind", "mode" ], "properties": { "revision_id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "kind": { "type": "string" }, "mode": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string" } } }, "WorkspaceChangesetResolveRecord": { "type": "object", "required": [ "expected_write_generation", "resolutions", "validation_evidence" ], "properties": { "expected_write_generation": { "type": "integer", "format": "int64" }, "resolutions": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceChangesetResolution" } }, "validation_evidence": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Nonblank evidence, at most 2048 UTF-8 bytes." }, "minItems": 1, "maxItems": 32 } } } } } }