{ "components": { "parameters": { "AppId": { "description": "Opaque account-owned app identifier.", "in": "path", "name": "id", "required": true, "schema": { "pattern": "^app_[a-f0-9]{20,64}$", "type": "string" } }, "DeploymentId": { "description": "Opaque immutable deployment identifier.", "in": "path", "name": "deploymentId", "required": true, "schema": { "pattern": "^deploy_[a-f0-9]{20,64}$", "type": "string" } }, "IdempotencyKey": { "description": "Caller-generated 8-128 character retry key. The service stores only a one-way hash.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 128, "minLength": 8, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$", "type": "string" } }, "WorkspaceCSRF": { "description": "The csrfToken from login or GET /v1/auth/session; retain its matching cookie too.", "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } }, "WorkspaceWebCollection": { "description": "Browser-safe hosted workspace collection.", "in": "path", "name": "collection", "required": true, "schema": { "enum": [ "projects", "sessions", "wiki", "skills", "agents", "workflows", "schedules" ], "type": "string" } } }, "schemas": { "AccountCapabilities": { "description": "Additive rollout handshake. Older backends omit this object, so clients must require an explicit true before exposing the corresponding workflow.", "properties": { "creditPurchases": { "description": "The serving backend has valid server-side purchase limits, Stripe Checkout credentials, a configured fulfillment webhook secret, trusted portal-edge signing, and return URLs.", "type": "boolean" }, "noSubscriptionInference": { "description": "Additional credits can fund hosted inference without an active subscription.", "type": "boolean" } }, "required": [ "creditPurchases", "noSubscriptionInference" ], "type": "object" }, "AccountEntitlements": { "description": "Purchased package eligibility. Every key is always present with an explicit boolean value (downgraded accounts get explicit false); clients rely on this object being complete. Compliance onboarding and zero-data-retention eligibility do not indicate that a protected environment is active; check the protection readiness fields on the account response.", "properties": { "complianceOnboarding": { "type": "boolean" }, "devopsWorkspace": { "type": "boolean" }, "extraComputerUse": { "description": "Business capability marker, internally compatible with the historical Secretary Pro bundle.", "type": "boolean" }, "hostedApps": { "description": "Account eligibility to create, stage, and activate small hosted apps. Existing apps remain readable and disposable when this becomes false.", "type": "boolean" }, "premiumModels": { "description": "Effective paid or administrator-granted Unlimited access to premium models.", "type": "boolean" }, "secretary": { "type": "boolean" }, "unlimitedHostedUsage": { "description": "Hosted compute is included without debiting credit lots. Nominal usage is still recorded; marketplace purchases remain metered.", "type": "boolean" }, "zeroDataRetentionEligible": { "type": "boolean" } }, "required": [ "premiumModels", "devopsWorkspace", "secretary", "extraComputerUse", "hostedApps", "complianceOnboarding", "zeroDataRetentionEligible", "unlimitedHostedUsage" ], "type": "object" }, "AccountResponse": { "properties": { "accessSource": { "enum": [ "billing", "admin_override" ], "type": "string" }, "accountKind": { "enum": [ "human", "agent" ], "type": "string" }, "accountPlan": { "description": "Internal compatibility plan derived from the stored tier and active billing state. New clients should display commercialTier instead.", "enum": [ "free", "devops", "secretary", "secretary_pro", "workspace_business_pro", "unlimited", "team", "enterprise", "legacy" ], "type": "string" }, "accountTier": { "enum": [ "beta_free", "devops", "secretary", "secretary_pro", "workspace_business_pro", "unlimited", "team", "enterprise", "lite", "pro", "business", "business_pro", "support_tip" ], "type": "string" }, "authProviders": { "items": { "enum": [ "google", "github" ], "type": "string" }, "type": "array" }, "billingAccountTier": { "description": "Stored Stripe-derived compatibility tier before any audited admin access override is applied.", "type": "string" }, "billingCommercialTier": { "description": "Public tier derived from Stripe billing state before any admin override.", "enum": [ "lite", "pro", "business", "business_pro", "unlimited", "no_subscription", "legacy" ], "type": "string" }, "billingInterval": { "enum": [ "month", "year" ], "type": "string" }, "billingPortalAvailable": { "type": "boolean" }, "billingReference": { "type": "string" }, "billingStatus": { "description": "Locally reconciled Stripe status. trial_ended is derived fail-closed when a trial deadline is missing or has passed before a terminal webhook arrives.", "type": "string" }, "cancelAtPeriodEnd": { "type": "boolean" }, "capabilities": { "$ref": "#/components/schemas/AccountCapabilities" }, "checkoutReferences": { "additionalProperties": false, "description": "Stripe-safe signed client_reference_id values for checkout links. Canonical lite, pro, business, and business_pro keys bind the exact Payment Link ID; temporary devops and secretary keys support the old website only while legacy issuance is enabled. Withheld while a nonterminal Stripe subscription exists so customers manage or repair that subscription in Billing Portal; returned for account-only/customer-only states and terminal canceled or incomplete_expired subscriptions when checkout signing is configured.", "properties": { "business": { "type": "string" }, "business_pro": { "description": "Signed checkout reference for the separate Business Pro plan.", "type": "string" }, "business_pro_yearly": { "description": "Link-bound reference for annual Business Pro billing.", "type": "string" }, "devops": { "type": "string" }, "lite": { "type": "string" }, "pro": { "type": "string" }, "secretary": { "type": "string" }, "secretary_pro": { "type": "string" } }, "type": "object" }, "checkoutReferencesExpireAt": { "description": "Expiration shared by the signed checkout references.", "format": "date-time", "type": "string" }, "claimedAt": { "type": "string" }, "commercialTier": { "description": "Current public tier derived from the effective plan; never inferred from legacy database tier spellings.", "enum": [ "lite", "pro", "business", "business_pro", "unlimited", "no_subscription", "legacy" ], "type": "string" }, "credits": { "$ref": "#/components/schemas/CreditSummary" }, "currentPeriodEnd": { "format": "date-time", "type": "string" }, "dataProfile": { "enum": [ "standard", "protected", "sovereign", "legacy" ], "type": "string" }, "effectiveDataProfile": { "enum": [ "standard", "protected", "sovereign", "legacy" ], "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "boolean" }, "entitlements": { "$ref": "#/components/schemas/AccountEntitlements" }, "error": { "type": "string" }, "handlesSensitiveData": { "type": "boolean" }, "hasStripeCustomer": { "type": "boolean" }, "hasStripeSubscription": { "type": "boolean" }, "legacyAccess": { "type": "boolean" }, "legacyTier": { "type": "string" }, "name": { "type": "string" }, "needsPasswordSetup": { "type": "boolean" }, "ok": { "type": "boolean" }, "onboardingComplete": { "type": "boolean" }, "onboardingRequired": { "description": "True only when a non-legacy Business account must complete its region and sensitive-data settings.", "type": "boolean" }, "protectedAllowedModels": { "items": { "type": "string" }, "type": "array" }, "protectedEnvironmentId": { "type": "string" }, "protectedEnvironmentReady": { "type": "boolean" }, "protectedInferenceConfigured": { "type": "boolean" }, "protectedRemoteControlEnabled": { "type": "boolean" }, "protectionStatus": { "enum": [ "none", "recommended", "onboarding_required", "active", "legacy" ], "type": "string" }, "region": { "type": "string" }, "stripeState": { "description": "Safe locally reconciled Stripe classification; no Stripe resource identifiers are exposed.", "enum": [ "account_only", "customer_only", "trialing", "trial_ended", "active", "past_due", "canceled", "unpaid", "paused", "incomplete", "incomplete_expired", "other" ], "type": "string" }, "subscriptionActionReason": { "enum": [ "no_subscription", "trial_ended", "payment_past_due", "subscription_paused", "subscription_unpaid", "subscription_inactive" ], "type": "string" }, "subscriptionActionRequired": { "description": "Raw Stripe billing attention state. This can be true while accessSource is admin_override or the account is grandfathered; clients must not use it to negate an explicit access grant.", "type": "boolean" }, "supportEmail": { "format": "email", "type": "string" }, "trialEndsAt": { "format": "date-time", "type": "string" }, "userId": { "type": "string" } }, "required": [ "ok" ], "type": "object" }, "ClankerApp": { "properties": { "activeDeploymentId": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "description": { "type": "string" }, "id": { "type": "string" }, "metadata": { "additionalProperties": true, "description": "Private authenticated control-plane metadata.", "type": "object" }, "name": { "type": "string" }, "projectId": { "type": "string" }, "publicAccessUncertain": { "description": "True when a lifecycle operation is pending or failed and the control plane cannot prove whether the public route is currently reachable. The owner should verify the URL and retry unpublish or deletion.", "type": "boolean" }, "publicUrl": { "description": "Stable opaque URL. Omitted only when the app is provably private (draft or confirmed unpublished); retained during error, pending, and deletion states because a lost host response can leave the route live.", "format": "uri", "type": "string" }, "publishedRevision": { "format": "int64", "type": "integer" }, "slug": { "type": "string" }, "status": { "enum": [ "draft", "published", "unpublished", "publishing_pending", "unpublishing_pending", "publication_error", "deleting", "deletion_error" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "versionCount": { "type": "integer" } }, "required": [ "id", "name", "slug", "status", "publishedRevision", "versionCount", "createdAt", "updatedAt" ], "type": "object" }, "ClankerAppAgenticConfig": { "additionalProperties": false, "description": "Explicit opt-in for platform-hosted Gemini and/or Kimi calls. Every numeric ceiling is required, can be configured downward, and cannot exceed the launch hard limits.", "properties": { "dailyRequestLimit": { "maximum": 25, "minimum": 1, "type": "integer" }, "maxInputCharacters": { "maximum": 16000, "minimum": 1, "type": "integer" }, "maxOutputTokens": { "maximum": 1024, "minimum": 1, "type": "integer" }, "providers": { "items": { "enum": [ "gemini", "kimi" ], "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "providers", "dailyRequestLimit", "maxInputCharacters", "maxOutputTokens" ], "type": "object" }, "ClankerAppCardItem": { "additionalProperties": false, "properties": { "body": { "maxLength": 2000, "type": "string" }, "meta": { "maxLength": 240, "type": "string" }, "title": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "title" ], "type": "object" }, "ClankerAppCardsBlock": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ClankerAppCardItem" }, "maxItems": 48, "minItems": 1, "type": "array" }, "title": { "maxLength": 120, "type": "string" }, "type": { "enum": [ "cards" ], "type": "string" } }, "required": [ "type", "items" ], "type": "object" }, "ClankerAppDataSummary": { "additionalProperties": false, "description": "Non-spoofable owner-only content counts derived from the canonical appSpec.", "properties": { "blockCount": { "maximum": 24, "minimum": 1, "type": "integer" }, "cardCount": { "maximum": 96, "minimum": 0, "type": "integer" }, "descriptionCharacters": { "maximum": 1000, "minimum": 0, "type": "integer" }, "listItemCount": { "maximum": 400, "minimum": 0, "type": "integer" }, "metricCount": { "maximum": 48, "minimum": 0, "type": "integer" }, "runtime": { "enum": [ "clanker-declarative-v1" ], "type": "string" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" }, "tableCellCount": { "maximum": 3000, "minimum": 0, "type": "integer" }, "tableCount": { "maximum": 24, "minimum": 0, "type": "integer" }, "tableRowCount": { "maximum": 500, "minimum": 0, "type": "integer" }, "textBlockCount": { "maximum": 24, "minimum": 0, "type": "integer" }, "textCharacterCount": { "minimum": 0, "type": "integer" }, "titleCharacters": { "maximum": 120, "minimum": 1, "type": "integer" } }, "required": [ "schemaVersion", "runtime", "blockCount", "titleCharacters", "descriptionCharacters", "metricCount", "tableCount", "tableRowCount", "tableCellCount", "textBlockCount", "textCharacterCount", "cardCount", "listItemCount" ], "type": "object" }, "ClankerAppDeployment": { "properties": { "activatedAt": { "format": "date-time", "type": "string" }, "appId": { "type": "string" }, "appSpecVersion": { "description": "1 is strict declarative v1. HTML and retained unavailable legacy deployments use 0 and are distinguished by runtime.", "enum": [ 0, 1 ], "type": "integer" }, "blockCount": { "maximum": 24, "minimum": 1, "type": "integer" }, "contentDigest": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "dataSummary": { "oneOf": [ { "$ref": "#/components/schemas/ClankerAppDataSummary" }, { "$ref": "#/components/schemas/ClankerHTMLDataSummary" }, { "$ref": "#/components/schemas/ClankerStaticDataSummary" } ] }, "entrypoint": { "type": "string" }, "exposure": { "oneOf": [ { "$ref": "#/components/schemas/ClankerAppExposure" }, { "$ref": "#/components/schemas/ClankerHTMLExposure" }, { "$ref": "#/components/schemas/ClankerStaticExposure" } ] }, "fileCount": { "maximum": 256, "minimum": 1, "type": "integer" }, "id": { "type": "string" }, "lastError": { "type": "string" }, "networkPolicy": { "enum": [ "none", "browser" ], "type": "string" }, "previewUrl": { "description": "Fresh five-minute deployment-scoped capability URL for private browser verification before activation. Present on eligible authenticated static deployment responses; request another authenticated response after expiry.", "format": "uri", "type": "string" }, "runtime": { "enum": [ "clanker-declarative-v1", "clanker-html-v1", "clanker-static-v1", "legacy-unavailable" ], "type": "string" }, "spa": { "type": "boolean" }, "specBytes": { "format": "int64", "maximum": 262144, "minimum": 1, "type": "integer" }, "status": { "enum": [ "staging", "ready", "active", "superseded", "failed" ], "type": "string" }, "totalBytes": { "format": "int64", "maximum": 268435456, "minimum": 1, "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "appId", "status", "runtime", "appSpecVersion", "createdAt", "updatedAt" ], "type": "object" }, "ClankerAppExposure": { "additionalProperties": false, "description": "Non-spoofable owner-only publication disclosure derived by the backend. Clients cannot submit or override it.", "properties": { "appDescription": { "type": "string" }, "appTitle": { "type": "string" }, "audience": { "enum": [ "anyone_with_link" ], "type": "string" }, "notice": { "enum": [ "Anyone with the link can view all app content." ], "type": "string" }, "publicFieldCount": { "minimum": 1, "type": "integer" }, "publicFields": { "items": { "maxLength": 80, "type": "string" }, "maxItems": 96, "type": "array" }, "publicFieldsTruncated": { "type": "boolean" }, "runtime": { "enum": [ "clanker-declarative-v1" ], "type": "string" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" } }, "required": [ "schemaVersion", "runtime", "audience", "notice", "appTitle", "publicFields", "publicFieldCount", "publicFieldsTruncated" ], "type": "object" }, "ClankerAppListBlock": { "additionalProperties": false, "properties": { "items": { "items": { "maxLength": 1000, "minLength": 1, "type": "string" }, "maxItems": 200, "minItems": 1, "type": "array" }, "title": { "maxLength": 120, "type": "string" }, "type": { "enum": [ "list" ], "type": "string" } }, "required": [ "type", "items" ], "type": "object" }, "ClankerAppMetricItem": { "additionalProperties": false, "properties": { "detail": { "maxLength": 240, "type": "string" }, "label": { "maxLength": 80, "minLength": 1, "type": "string" }, "value": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "label", "value" ], "type": "object" }, "ClankerAppMetricsBlock": { "additionalProperties": false, "properties": { "items": { "items": { "$ref": "#/components/schemas/ClankerAppMetricItem" }, "maxItems": 12, "minItems": 1, "type": "array" }, "title": { "maxLength": 120, "type": "string" }, "type": { "enum": [ "metrics" ], "type": "string" } }, "required": [ "type", "items" ], "type": "object" }, "ClankerAppPublicationPrecondition": { "additionalProperties": false, "description": "Optional compare-and-set guard for publication recovery. When supplied, activation or unpublish succeeds only if the app still has this published revision; a mismatch returns 409 before the public route is changed.", "properties": { "expectedPublishedRevision": { "format": "int64", "minimum": 0, "type": "integer" } }, "type": "object" }, "ClankerAppSpec": { "additionalProperties": false, "description": "Canonical declarative UI data only. Every string is rendered as inert text. Unknown or duplicate keys, unsafe controls, credential signatures, non-string display scalars, and canonical JSON larger than 256 KiB are rejected.", "properties": { "blocks": { "items": { "oneOf": [ { "$ref": "#/components/schemas/ClankerAppMetricsBlock" }, { "$ref": "#/components/schemas/ClankerAppTextBlock" }, { "$ref": "#/components/schemas/ClankerAppTableBlock" }, { "$ref": "#/components/schemas/ClankerAppCardsBlock" }, { "$ref": "#/components/schemas/ClankerAppListBlock" } ] }, "maxItems": 24, "minItems": 1, "type": "array" }, "description": { "maxLength": 1000, "type": "string" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" }, "theme": { "default": "light", "enum": [ "light", "dark", "slate", "ocean" ], "type": "string" }, "title": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "schemaVersion", "title", "blocks" ], "type": "object" }, "ClankerAppTableBlock": { "additionalProperties": false, "properties": { "columns": { "items": { "maxLength": 80, "minLength": 1, "type": "string" }, "maxItems": 12, "minItems": 1, "type": "array", "uniqueItems": true }, "rows": { "description": "Each row must have exactly the same number of string cells as columns. The backend also enforces 500 rows and 3,000 cells across the complete appSpec.", "items": { "items": { "maxLength": 500, "type": "string" }, "maxItems": 12, "minItems": 1, "type": "array" }, "maxItems": 250, "type": "array" }, "title": { "maxLength": 120, "type": "string" }, "type": { "enum": [ "table" ], "type": "string" } }, "required": [ "type", "columns", "rows" ], "type": "object" }, "ClankerAppTextBlock": { "additionalProperties": false, "properties": { "body": { "maxLength": 8000, "minLength": 1, "type": "string" }, "title": { "maxLength": 120, "type": "string" }, "type": { "enum": [ "text" ], "type": "string" } }, "required": [ "type", "body" ], "type": "object" }, "ClankerAppsResponse": { "properties": { "app": { "$ref": "#/components/schemas/ClankerApp" }, "apps": { "items": { "$ref": "#/components/schemas/ClankerApp" }, "type": "array" }, "deployment": { "$ref": "#/components/schemas/ClankerAppDeployment" }, "deployments": { "items": { "$ref": "#/components/schemas/ClankerAppDeployment" }, "type": "array" }, "error": { "type": "string" }, "idempotent": { "type": "boolean" }, "maxApps": { "description": "Maximum hosted App records for the authenticated account. Free accounts receive two slots.", "type": "integer" }, "maxBlocks": { "type": "integer" }, "maxFailedVersions": { "description": "Maximum retained failed deployment records per app. New idempotency keys are rejected at this cap; an identical existing-key retry remains allowed.", "type": "integer" }, "maxHtmlBytes": { "type": "integer" }, "maxSpecBytes": { "type": "integer" }, "maxTableColumns": { "type": "integer" }, "maxTableRows": { "type": "integer" }, "maxTotalVersions": { "description": "Hard retained deployment-record cap across all statuses.", "type": "integer" }, "maxVersions": { "description": "Admission cap for new ready/inflight deployment keys. An existing failed key may still be retried for recoverability, subject to the hard total cap.", "type": "integer" }, "ok": { "type": "boolean" }, "publishedRevision": { "description": "Exact publication revision reserved by activation or unpublish. Present on success and on every later error after the revision increment, and omitted when validation or compare-and-set fails before an increment. An idempotent success returns the currently confirmed revision. Store this value when issuing a guarded recovery operation.", "format": "int64", "minimum": 0, "type": "integer" }, "retryAfter": { "description": "Seconds before a rate-limited mutation should be retried.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "ok" ], "type": "object" }, "ClankerHTMLDataSummary": { "additionalProperties": false, "description": "Non-spoofable owner-only byte counts derived from the staged HTML.", "properties": { "fileCount": { "enum": [ 1 ], "type": "integer" }, "runtime": { "enum": [ "clanker-html-v1" ], "type": "string" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" }, "totalBytes": { "format": "int64", "maximum": 2097152, "minimum": 1, "type": "integer" } }, "required": [ "schemaVersion", "runtime", "fileCount", "totalBytes" ], "type": "object" }, "ClankerHTMLExposure": { "additionalProperties": false, "description": "Non-spoofable owner-only disclosure derived by the backend for executable HTML deployments.", "properties": { "agentic": { "additionalProperties": false, "properties": { "dailyRequestLimit": { "maximum": 25, "minimum": 1, "type": "integer" }, "enabled": { "enum": [ true ], "type": "boolean" }, "endpoint": { "description": "Replace `{slug}` with the second path segment from the current published app URL so the endpoint remains stable after SPA history navigation.", "enum": [ "/a/{slug}/__clanker/llm" ], "type": "string" }, "maxInputCharacters": { "maximum": 16000, "minimum": 1, "type": "integer" }, "maxOutputTokens": { "maximum": 1024, "minimum": 1, "type": "integer" }, "providers": { "items": { "enum": [ "gemini", "kimi" ], "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "enabled", "endpoint", "providers", "dailyRequestLimit", "maxInputCharacters", "maxOutputTokens" ], "type": "object" }, "audience": { "enum": [ "anyone_with_link" ], "type": "string" }, "browserNetwork": { "enum": [ "user_defined" ], "type": "string" }, "executesUserCode": { "enum": [ true ], "type": "boolean" }, "notice": { "enum": [ "Anyone with the link can run and interact with this app." ], "type": "string" }, "runtime": { "enum": [ "clanker-html-v1" ], "type": "string" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" } }, "required": [ "schemaVersion", "runtime", "audience", "notice", "executesUserCode", "browserNetwork" ], "type": "object" }, "ClankerSandboxAppSource": { "additionalProperties": false, "description": "Server-to-server handoff from an account-bound sandbox's ephemeral /workspace. Preflight with a manifest-only snapshot and supply its digest; the backend rechecks the manifest, streams each verified file as raw bytes, and takes a final manifest-only snapshot before finalization. Persistent /data is never accepted as deployment source.", "properties": { "entrypoint": { "maxLength": 512, "minLength": 1, "type": "string" }, "expectedContentDigest": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "expectedFileCount": { "maximum": 256, "minimum": 1, "type": "integer" }, "expectedTotalBytes": { "format": "int64", "maximum": 268435456, "minimum": 1, "type": "integer" }, "path": { "maxLength": 1024, "minLength": 10, "pattern": "^/workspace(?:/.*)?$", "type": "string" }, "sandboxId": { "maxLength": 128, "minLength": 1, "type": "string" }, "spa": { "type": "boolean" } }, "required": [ "sandboxId", "path", "entrypoint", "spa", "expectedContentDigest" ], "type": "object" }, "ClankerStaticBundle": { "additionalProperties": false, "description": "Immutable subpath-safe static output. Files are normalized, sorted, hashed, and served under /a/{slug}/. Browser builds must use relative asset URLs rather than root-absolute /assets URLs.", "properties": { "contentDigest": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "entrypoint": { "maxLength": 512, "minLength": 1, "type": "string" }, "fileCount": { "maximum": 256, "minimum": 1, "type": "integer" }, "files": { "items": { "$ref": "#/components/schemas/ClankerStaticBundleFile" }, "maxItems": 256, "minItems": 1, "type": "array" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" }, "spa": { "type": "boolean" }, "totalBytes": { "format": "int64", "maximum": 50331648, "minimum": 1, "type": "integer" } }, "required": [ "schemaVersion", "entrypoint", "spa", "files" ], "type": "object" }, "ClankerStaticBundleFile": { "additionalProperties": false, "properties": { "contentBase64": { "format": "byte", "type": "string" }, "path": { "maxLength": 512, "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "size": { "format": "int64", "maximum": 16777216, "minimum": 0, "type": "integer" } }, "required": [ "path", "contentBase64" ], "type": "object" }, "ClankerStaticDataSummary": { "additionalProperties": false, "description": "Non-spoofable owner-only file and byte counts derived from the canonical static bundle.", "properties": { "entrypoint": { "maxLength": 512, "minLength": 1, "type": "string" }, "fileCount": { "maximum": 256, "minimum": 1, "type": "integer" }, "runtime": { "enum": [ "clanker-static-v1" ], "type": "string" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" }, "spa": { "type": "boolean" }, "totalBytes": { "format": "int64", "maximum": 268435456, "minimum": 1, "type": "integer" } }, "required": [ "schemaVersion", "runtime", "entrypoint", "spa", "fileCount", "totalBytes" ], "type": "object" }, "ClankerStaticExposure": { "additionalProperties": false, "description": "Non-spoofable owner-only disclosure derived by the backend for executable multi-file static deployments.", "properties": { "agentic": { "additionalProperties": false, "properties": { "dailyRequestLimit": { "maximum": 25, "minimum": 1, "type": "integer" }, "enabled": { "enum": [ true ], "type": "boolean" }, "endpoint": { "description": "Logical managed endpoint. Browser code derives the exact App base for either `/a/{slug}` publication or signed `/p/{app}/{deployment}/{expiry}/{signature}` preview before appending `/__clanker/llm`.", "enum": [ "/a/{slug}/__clanker/llm" ], "type": "string" }, "maxInputCharacters": { "maximum": 16000, "minimum": 1, "type": "integer" }, "maxOutputTokens": { "maximum": 1024, "minimum": 1, "type": "integer" }, "providers": { "items": { "enum": [ "gemini", "kimi" ], "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "enabled", "endpoint", "providers", "dailyRequestLimit", "maxInputCharacters", "maxOutputTokens" ], "type": "object" }, "audience": { "enum": [ "anyone_with_link" ], "type": "string" }, "browserNetwork": { "enum": [ "user_defined" ], "type": "string" }, "executesUserCode": { "enum": [ true ], "type": "boolean" }, "notice": { "enum": [ "Anyone with the link can run and interact with this app." ], "type": "string" }, "runtime": { "enum": [ "clanker-static-v1" ], "type": "string" }, "schemaVersion": { "enum": [ 1 ], "type": "integer" } }, "required": [ "schemaVersion", "runtime", "audience", "notice", "executesUserCode", "browserNetwork" ], "type": "object" }, "CreateClankerAppDeploymentRequest": { "additionalProperties": false, "oneOf": [ { "not": { "anyOf": [ { "required": [ "appSpec" ] }, { "required": [ "staticBundle" ] }, { "required": [ "sandboxSource" ] } ] }, "required": [ "html" ] }, { "not": { "anyOf": [ { "required": [ "html" ] }, { "required": [ "staticBundle" ] }, { "required": [ "sandboxSource" ] }, { "required": [ "agentic" ] } ] }, "required": [ "appSpec" ] }, { "not": { "anyOf": [ { "required": [ "html" ] }, { "required": [ "appSpec" ] }, { "required": [ "sandboxSource" ] } ] }, "required": [ "staticBundle" ] }, { "not": { "anyOf": [ { "required": [ "html" ] }, { "required": [ "appSpec" ] }, { "required": [ "staticBundle" ] } ] }, "required": [ "sandboxSource" ] } ], "properties": { "agentic": { "$ref": "#/components/schemas/ClankerAppAgenticConfig" }, "appSpec": { "$ref": "#/components/schemas/ClankerAppSpec" }, "html": { "description": "Self-contained HTML/CSS/JavaScript served byte-for-byte as a public app. Use external resources and browser APIs as the app requires.", "maxLength": 2097152, "minLength": 1, "type": "string" }, "sandboxSource": { "$ref": "#/components/schemas/ClankerSandboxAppSource" }, "staticBundle": { "$ref": "#/components/schemas/ClankerStaticBundle" } }, "type": "object" }, "CreateClankerAppRequest": { "additionalProperties": false, "properties": { "description": { "maxLength": 500, "type": "string" }, "metadata": { "additionalProperties": true, "description": "Private control-plane metadata. Never copied to the public manifest.", "maxProperties": 100, "type": "object" }, "name": { "maxLength": 80, "minLength": 1, "type": "string" }, "projectId": { "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreditAccountResponse": { "properties": { "credits": { "$ref": "#/components/schemas/CreditSummary" }, "error": { "type": "string" }, "nextCursor": { "format": "date-time", "type": "string" }, "ok": { "type": "boolean" }, "transactions": { "items": { "$ref": "#/components/schemas/CreditTransaction" }, "type": "array" } }, "required": [ "ok" ], "type": "object" }, "CreditSummary": { "properties": { "accountVersion": { "format": "int64", "minimum": 0, "type": "integer" }, "additionalBalanceMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "computeMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "expiringMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "marketplaceMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "policyVersion": { "format": "int64", "minimum": 1, "type": "integer" }, "proAllowanceExpiresAt": { "format": "date-time", "type": "string" }, "proAllowanceMicrounits": { "deprecated": true, "description": "Deprecated former Secretary Pro allowance; not the current public Pro quota.", "format": "int64", "minimum": 0, "type": "integer" }, "referralRegistrationCredits": { "format": "int64", "minimum": 0, "type": "integer" }, "referralSubscriptionCredits": { "format": "int64", "minimum": 0, "type": "integer" }, "reservedMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "subscriptionBalanceMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "subscriptionPeriodEndsAt": { "format": "date-time", "type": "string" }, "subscriptionQuotaMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "totalMicrounits": { "format": "int64", "minimum": 0, "type": "integer" }, "usageMode": { "enum": [ "metered", "unlimited" ], "type": "string" } }, "required": [ "accountVersion", "totalMicrounits", "computeMicrounits", "marketplaceMicrounits", "expiringMicrounits", "reservedMicrounits", "subscriptionBalanceMicrounits", "additionalBalanceMicrounits", "subscriptionQuotaMicrounits", "usageMode", "proAllowanceMicrounits", "referralRegistrationCredits", "referralSubscriptionCredits", "policyVersion" ], "type": "object" }, "CreditTransaction": { "properties": { "amountMicrounits": { "format": "int64", "type": "integer" }, "balanceClass": { "enum": [ "subscription", "additional" ], "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "kind": { "enum": [ "grant", "debit", "reversal", "revoke" ], "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "scope": { "enum": [ "compute", "universal" ], "type": "string" }, "sessionId": { "type": "string" }, "sourceId": { "type": "string" }, "sourceType": { "type": "string" } }, "required": [ "id", "kind", "amountMicrounits", "scope", "balanceClass", "sourceType", "createdAt" ], "type": "object" }, "ErrorResponse": { "properties": { "code": { "description": "Optional stable machine-readable error code.", "type": "string" }, "error": { "type": "string" }, "ok": { "type": "boolean" }, "provider": { "description": "Optional sanitized inference provider identifier.", "enum": [ "gemini" ], "type": "string" }, "providerReason": { "description": "Optional sanitized provider enum; upstream prose and response bodies are never returned.", "type": "string" }, "replacement": { "description": "Optional replacement API path for a retired operation.", "type": "string" } }, "required": [ "ok", "error" ], "type": "object" }, "ExternalAgentSessionResponse": { "properties": { "item": { "$ref": "#/components/schemas/WorkspaceWebResource" }, "ok": { "type": "boolean" }, "run": { "$ref": "#/components/schemas/WorkspaceSessionRun" } }, "required": [ "ok", "item", "run" ], "type": "object" }, "ExternalAgentSessionStart": { "additionalProperties": false, "properties": { "agentName": { "maxLength": 120, "minLength": 1, "type": "string" }, "idempotencyKey": { "maxLength": 200, "minLength": 12, "type": "string" }, "initialMessage": { "description": "The user's task as a visible initial message; never include credentials or private reasoning", "maxLength": 65536, "minLength": 1, "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "projectId": { "description": "Exact authorized project ID or general for unassigned files", "type": "string" }, "provider": { "enum": [ "claude", "chatgpt", "codex", "custom" ], "type": "string" } }, "required": [ "name", "provider", "agentName", "initialMessage", "idempotencyKey" ], "type": "object" }, "InferenceChatCompletionRequest": { "properties": { "effort": { "description": "For Astra, low (default), medium, high, xhigh, or max; none/minimal map to low. Omitted effort uses the saved thinking selection, or low for the bare model. An explicit effort that conflicts with a saved thinking selection is rejected. Also consumed by the Kimi (Moonshot) route and forwarded as reasoning_effort. Ignored by the Gemini route, which controls reasoning via a \"-thinking\" model-string suffix. The Kimi client tolerates the upstream rejecting this parameter and retries once without it.", "example": "high", "type": "string" }, "max_tokens": { "description": "Optional caller-requested output-token ceiling. When omitted, the selected provider's native limit applies; values outside 1–65,536 are rejected.", "maximum": 65536, "minimum": 1, "type": "integer" }, "messages": { "items": { "$ref": "#/components/schemas/InferenceChatMessage" }, "type": "array" }, "metadata": { "additionalProperties": true, "description": "Accepted for request compatibility but not persisted or forwarded. The service records only a fixed safe metadata subset generated by the server.", "type": "object" }, "model": { "description": "OpenAI accepts gpt-6-astra or saved gpt-6-astra-thinking-{level} selections, where level is low, medium, high, xhigh, or max. Saved selections are resolved to the canonical provider model with that reasoning effort. Gemini and Kimi accept a free-form model identifier. Clanker DevOps and Clanker Secretary accounts pass a supported model ID or resource name (a Gemini model for provider=gemini, a Moonshot/Kimi model id for provider=kimi). Activated protected and sovereign accounts remain constrained by the server-side model allowlist.", "example": "gemini-3.8-flash", "type": "string" }, "provider": { "description": "Optional Standard-route model provider selector. Supported Gemini aliases (gemini, google, google-gemini) and Kimi aliases (kimi, moonshot) are accepted for Clanker DevOps and Clanker Secretary accounts; Gemini is the default when omitted. The Kimi route requires a server-side KIMI_API_KEY and otherwise returns 501. OpenAI (openai) supports gpt-6-astra and saved gpt-6-astra-thinking-{level} selections for effective paid or Unlimited accounts, requires CLANKER_CLOUD_OPENAI_API_KEY, and supports non-streaming requests only. Free, lapsed, legacy-only, protected and sovereign accounts cannot use Astra. An omitted provider with model=gpt-6-astra routes to OpenAI. Protected and sovereign accounts use only their server-approved regional route after activation.", "example": "gemini", "type": "string" }, "stream": { "default": false, "description": "When true, return OpenAI-style server-sent event chunks and a final done event.", "type": "boolean" }, "token": { "description": "Optional body token compatibility field. Prefer Authorization Bearer or X-API-Key.", "type": "string" }, "web_search": { "default": false, "description": "Enables provider-managed Google Search grounding for non-streaming Gemini requests. Accepted only from the signed workspace.clankercloud.ai edge for Standard accounts; direct, desktop, protected, sovereign, Kimi, and streaming requests fail closed.", "type": "boolean" }, "workspace_tools": { "description": "Enables the provider-native call_workspace_tool function and limits its action enum. Accepted only from the signed workspace.clankercloud.ai edge on non-streaming requests. This is a model-visibility limit; the Workspace controller separately enforces account and agent authorization before execution.", "items": { "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)+$", "type": "string" }, "maxItems": 256, "type": "array", "uniqueItems": true } }, "required": [ "model", "messages" ], "type": "object" }, "InferenceChatMessage": { "properties": { "content": { "example": "Explain this alert in one sentence.", "type": "string" }, "name": { "enum": [ "call_workspace_tool" ], "type": "string" }, "role": { "description": "Chat role. Supported values are system, user, assistant, and tool.", "example": "user", "type": "string" }, "tool_call_id": { "description": "Exact provider call id being answered by a tool-role message.", "type": "string" }, "tool_calls": { "items": { "$ref": "#/components/schemas/InferenceToolCall" }, "maxItems": 8, "type": "array" } }, "required": [ "role" ], "type": "object" }, "InferenceToolCall": { "additionalProperties": false, "properties": { "function": { "additionalProperties": false, "properties": { "arguments": { "description": "JSON object string containing action and arguments.", "type": "string" }, "name": { "enum": [ "call_workspace_tool" ], "type": "string" } }, "required": [ "name", "arguments" ], "type": "object" }, "id": { "type": "string" }, "provider_state": { "additionalProperties": false, "properties": { "openai_reasoning": { "description": "Opaque encrypted Responses reasoning items; echo unchanged with the tool call.", "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, "thought_signature": { "description": "Opaque provider state that must be echoed unchanged in later history.", "type": "string" } }, "type": "object" }, "type": { "enum": [ "function" ], "type": "string" } }, "required": [ "id", "type", "function" ], "type": "object" }, "LoginRequest": { "properties": { "password": { "type": "string" }, "promoCode": { "description": "Optional credit promo code redeemed atomically with login.", "maxLength": 80, "minLength": 4, "type": "string" }, "sessionMode": { "enum": [ "cookie" ], "type": "string" }, "termsAccepted": { "type": "boolean" }, "termsVersion": { "type": "string" }, "username": { "type": "string" } }, "required": [ "username", "password", "sessionMode" ], "type": "object" }, "LoginResponse": { "properties": { "accountKind": { "enum": [ "human", "agent" ], "type": "string" }, "backupCode": { "type": "string" }, "claimedAt": { "type": "string" }, "csrfToken": { "type": "string" }, "email": { "type": "string" }, "emailVerified": { "type": "boolean" }, "error": { "type": "string" }, "ok": { "type": "boolean" }, "promoAmountMicrounits": { "format": "int64", "type": "integer" }, "promoApplied": { "type": "boolean" }, "sessionMode": { "enum": [ "api", "cookie" ], "type": "string" }, "signupGrantAmountMicrounits": { "description": "Welcome-credit grant applied atomically when this response created a new account.", "format": "int64", "type": "integer" }, "token": { "type": "string" }, "userId": { "type": "string" } }, "required": [ "ok" ], "type": "object" }, "RegisterRequest": { "properties": { "handlesSensitiveData": { "description": "Generic onboarding answer used to recommend Clanker Secretary Pro protected onboarding; it does not inspect or restrict use cases.", "type": "boolean" }, "metadata": { "additionalProperties": true, "description": "Arbitrary JSON payload", "type": "object" }, "name": { "type": "string" }, "password": { "maxLength": 128, "minLength": 15, "type": "string" }, "promoCode": { "description": "Optional credit promo code redeemed atomically with registration.", "maxLength": 80, "minLength": 4, "type": "string" }, "referralCode": { "description": "Optional referral code captured before registration.", "maxLength": 80, "minLength": 4, "type": "string" }, "region": { "description": "Preferred managed-runtime region or protected-environment region identifier.", "type": "string" }, "sessionMode": { "enum": [ "cookie" ], "type": "string" }, "termsAccepted": { "description": "Required affirmative acceptance.", "type": "boolean" }, "termsVersion": { "description": "Required exact current version.", "type": "string" }, "username": { "type": "string" } }, "required": [ "username", "password", "termsAccepted", "termsVersion", "sessionMode" ], "type": "object" }, "WorkspaceAgentRestoreRequest": { "additionalProperties": false, "properties": { "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expectedRevision" ], "type": "object" }, "WorkspaceAgentSelfCapabilityResponse": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^(base-agent|agent_[a-f0-9]{24})$", "type": "string" }, "canEditProjectSkills": { "type": "boolean" }, "capability": { "description": "Opaque short-lived value for the trusted client executor only", "type": "string" }, "error": { "type": "string" }, "expiresAt": { "format": "date-time", "type": "string" }, "ok": { "type": "boolean" }, "projectId": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } }, "required": [ "ok", "canEditProjectSkills" ], "type": "object" }, "WorkspaceAgentSelfUpdateRequest": { "additionalProperties": false, "properties": { "avatar": { "additionalProperties": false, "nullable": true, "properties": { "assetId": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "columns": { "enum": [ 4 ], "type": "integer" }, "generated": { "type": "boolean" }, "height": { "maximum": 2048, "minimum": 512, "type": "integer" }, "layout": { "enum": [ "clanker.agent-avatar.v1" ], "type": "string" }, "mimeType": { "enum": [ "image/png", "image/jpeg" ], "type": "string" }, "rows": { "enum": [ 4 ], "type": "integer" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "width": { "maximum": 2048, "minimum": 512, "type": "integer" } }, "required": [ "assetId", "mimeType", "sha256", "width", "height", "columns", "rows", "layout", "generated" ], "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "instructions": { "maxLength": 24000, "type": "string" }, "mention": { "pattern": "^[a-z0-9](?:[a-z0-9-]{0,46}[a-z0-9])?$", "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name", "mention", "description", "instructions", "expectedRevision" ], "type": "object" }, "WorkspaceAgentSkillCreateRequest": { "additionalProperties": false, "properties": { "data": { "additionalProperties": true, "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "WorkspaceAgentSkillUpdateRequest": { "additionalProperties": false, "properties": { "data": { "additionalProperties": true, "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name", "expectedRevision" ], "type": "object" }, "WorkspaceAgentVersion": { "additionalProperties": false, "properties": { "recordedAt": { "format": "date-time", "type": "string" }, "restoredFromRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "snapshot": { "$ref": "#/components/schemas/WorkspaceWebResource" }, "source": { "enum": [ "create", "update", "restore", "backfill" ], "type": "string" } }, "required": [ "revision", "snapshot", "source", "recordedAt" ], "type": "object" }, "WorkspaceAgentVersionsResponse": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "item": { "$ref": "#/components/schemas/WorkspaceWebResource" }, "ok": { "type": "boolean" }, "versions": { "items": { "$ref": "#/components/schemas/WorkspaceAgentVersion" }, "maxItems": 25, "type": "array" } }, "required": [ "ok" ], "type": "object" }, "WorkspaceAppBuild": { "additionalProperties": false, "properties": { "appId": { "pattern": "^app_[a-f0-9]{20,64}$", "type": "string" }, "attempt": { "minimum": 0, "type": "integer" }, "buildSpec": { "additionalProperties": true, "type": "object" }, "createdAt": { "format": "date-time", "type": "string" }, "deploymentId": { "type": "string" }, "error": { "maxLength": 2000, "type": "string" }, "errorCode": { "type": "string" }, "fallbackModel": { "type": "string" }, "fallbackProvider": { "enum": [ "gemini", "kimi", "openai" ], "type": "string" }, "finishedAt": { "format": "date-time", "type": "string" }, "id": { "pattern": "^build_[a-f0-9]{24}$", "type": "string" }, "managedModelAllowed": { "type": "boolean" }, "managedServicesAllowed": { "description": "Enable the Workspace-only managed app runtime and builder guidance.", "type": "boolean" }, "model": { "type": "string" }, "phase": { "enum": [ "queued", "understand", "explore", "plan", "build", "checkpoint", "repair", "inspect", "stage", "complete", "failed", "cancelled" ], "type": "string" }, "progress": { "maxLength": 500, "type": "string" }, "provider": { "enum": [ "gemini", "kimi", "openai" ], "type": "string" }, "request": { "type": "string" }, "result": { "additionalProperties": true, "type": "object" }, "sandboxId": { "type": "string" }, "sessionId": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" }, "startedAt": { "format": "date-time", "type": "string" }, "status": { "enum": [ "queued", "running", "cancel_requested", "succeeded", "failed", "cancelled" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "appId", "request", "model", "provider", "status", "phase", "buildSpec", "result", "attempt", "createdAt", "updatedAt" ], "type": "object" }, "WorkspaceAppBuildCreateRequest": { "additionalProperties": false, "properties": { "agentContext": { "maxLength": 16384, "type": "string" }, "appId": { "pattern": "^app_[a-f0-9]{20,64}$", "type": "string" }, "baseDeploymentId": { "description": "Exact deployment whose source is being changed; must match baseSourceSnapshotId.", "type": "string" }, "baseSourceSnapshotId": { "pattern": "^source_[a-f0-9]{24}$", "type": "string" }, "fallbackModel": { "maxLength": 160, "type": "string" }, "fallbackProvider": { "enum": [ "gemini", "kimi", "openai" ], "type": "string" }, "managedModelAllowed": { "default": false, "description": "Explicit authenticated-owner approval for the isolated builder to request a frozen managed-model capability. This does not publish the App or expose provider credentials.", "type": "boolean" }, "managedServicesAllowed": { "description": "Enable the Workspace-only managed app runtime and builder guidance.", "type": "boolean" }, "model": { "maxLength": 160, "type": "string" }, "projectContext": { "maxLength": 16384, "type": "string" }, "provider": { "enum": [ "gemini", "kimi", "openai" ], "type": "string" }, "request": { "maxLength": 65536, "minLength": 1, "type": "string" }, "sessionId": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } }, "required": [ "appId", "request" ], "type": "object" }, "WorkspaceAppBuildEvent": { "additionalProperties": false, "properties": { "buildId": { "pattern": "^build_[a-f0-9]{24}$", "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "format": "int64", "minimum": 1, "type": "integer" }, "message": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "phase": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "buildId", "phase", "status", "message", "metadata", "createdAt" ], "type": "object" }, "WorkspaceAppBuildResponse": { "additionalProperties": false, "properties": { "build": { "$ref": "#/components/schemas/WorkspaceAppBuild" }, "builds": { "items": { "$ref": "#/components/schemas/WorkspaceAppBuild" }, "maxItems": 100, "type": "array" }, "error": { "type": "string" }, "events": { "items": { "$ref": "#/components/schemas/WorkspaceAppBuildEvent" }, "maxItems": 200, "type": "array" }, "idempotent": { "type": "boolean" }, "nextCursor": { "format": "int64", "minimum": 0, "type": "integer" }, "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "WorkspaceBaseAgent": { "additionalProperties": false, "properties": { "avatar": { "additionalProperties": false, "properties": { "assetId": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "columns": { "enum": [ 4 ], "type": "integer" }, "generated": { "type": "boolean" }, "height": { "maximum": 2048, "minimum": 512, "type": "integer" }, "layout": { "enum": [ "clanker.agent-avatar.v1" ], "type": "string" }, "mimeType": { "enum": [ "image/png", "image/jpeg" ], "type": "string" }, "rows": { "enum": [ 4 ], "type": "integer" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "width": { "maximum": 2048, "minimum": 512, "type": "integer" } }, "required": [ "assetId", "mimeType", "sha256", "width", "height", "columns", "rows", "layout", "generated" ], "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "displayName": { "default": "My Agent", "maxLength": 120, "minLength": 1, "type": "string" }, "instructions": { "maxLength": 24000, "type": "string" }, "legacyMentions": { "items": { "enum": [ "secretary" ], "type": "string" }, "type": "array" }, "mention": { "default": "agent", "description": "Mention without the @ prefix", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,46}[a-z0-9])?$", "type": "string" }, "voiceSpeaker": { "enum": [ "angus", "asteria", "arcas", "orion", "orpheus", "athena", "luna", "zeus", "perseus", "helios", "hera", "stella", "google-lite:kore", "google-lite:puck", "google-lite:charon", "google-lite:fenrir", "google-lite:aoede", "google-lite:leda", "google-lite:orus", "google-lite:zephyr", "google:kore", "google:puck", "google:charon", "google:fenrir", "google:aoede", "google:leda", "google:orus", "google:zephyr" ], "type": "string" } }, "required": [ "displayName", "mention", "description", "instructions", "legacyMentions" ], "type": "object" }, "WorkspaceCustomToolDraftRequest": { "properties": { "description": { "maxLength": 4000, "type": "string" }, "enabled": { "enum": [ false ], "type": "boolean" }, "expectedRevision": { "format": "int64", "type": "integer" }, "name": { "maxLength": 120, "type": "string" }, "projectId": { "type": "string" }, "slug": { "pattern": "^[a-z][a-z0-9-]{0,47}$", "type": "string" }, "spec": { "$ref": "#/components/schemas/WorkspaceCustomToolSpec" } }, "required": [ "name", "slug", "spec" ], "type": "object" }, "WorkspaceCustomToolRunRequest": { "description": "Four active runs per account. Supply an exact enabled version, or an exact draftRevision for owner testing. Version 0 is a draft. Draft runs are unavailable to agents. An agent invocation must also match its saved customToolRefs. An unapproved run waits unless the session is in yolo mode. approved means the owner or the existing session approval controller approved this manifest. Nested scripts receive no credentials and cannot expand this authority.", "properties": { "agentId": { "type": "string" }, "approved": { "type": "boolean" }, "draftRevision": { "type": "integer" }, "idempotencyKey": { "maxLength": 160, "minLength": 12, "type": "string" }, "input": { "additionalProperties": true, "type": "object" }, "projectId": { "type": "string" }, "sessionId": { "type": "string" }, "toolId": { "type": "string" }, "version": { "type": "integer" }, "workspaceRunId": { "type": "string" } }, "required": [ "toolId", "input", "idempotencyKey" ], "type": "object" }, "WorkspaceCustomToolSpec": { "description": "A definition is limited to 512 KiB. Dependencies resolve to exact account-owned enabled versions; resource snapshots are capped at 2 MiB. The shared root budget limits all nested tools and agents. Scripts use run(input, ctx); ctx exposes selected resources, local document paths and a scoped call broker. HTML runs in an opaque sandbox with only a same-tool run bridge.", "properties": { "agentIds": { "items": { "type": "string" }, "maxItems": 16, "type": "array" }, "articleIds": { "items": { "type": "string" }, "maxItems": 16, "type": "array" }, "builtinIds": { "items": { "type": "string" }, "type": "array" }, "dependencyBindings": { "additionalProperties": { "type": "string" }, "description": "Package-local dependency identifiers mapped to attached owned identifiers of the same kind. Bindings cannot add access or shadow another attached resource.", "type": "object" }, "documents": { "items": { "properties": { "path": { "type": "string" }, "projectId": { "type": "string" }, "revision": { "minimum": 1, "type": "integer" } }, "required": [ "projectId", "path", "revision" ], "type": "object" }, "maxItems": 16, "type": "array" }, "html": { "type": "string" }, "inputs": { "items": { "properties": { "default": {}, "label": { "type": "string" }, "name": { "type": "string" }, "required": { "type": "boolean" }, "type": { "enum": [ "string", "number", "boolean", "object", "array", "document" ], "type": "string" } }, "required": [ "name", "type" ], "type": "object" }, "maxItems": 32, "type": "array" }, "maxCalls": { "maximum": 64, "minimum": 1, "type": "integer" }, "outputType": { "enum": [ "any", "string", "number", "boolean", "object", "array" ], "type": "string" }, "skillIds": { "items": { "type": "string" }, "maxItems": 16, "type": "array" }, "steps": { "items": { "properties": { "id": { "type": "string" }, "input": {}, "kind": { "enum": [ "python", "javascript", "tool", "agent", "inference", "transform", "output" ], "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "when": { "additionalProperties": true, "type": "object" } }, "required": [ "id", "kind" ], "type": "object" }, "maxItems": 32, "type": "array" }, "timeoutSeconds": { "maximum": 300, "minimum": 1, "type": "integer" }, "toolRefs": { "items": { "properties": { "id": { "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "id", "version" ], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": [ "inputs", "steps", "outputType", "timeoutSeconds", "maxCalls" ], "type": "object" }, "WorkspaceEmailSyncState": { "description": "A mailbox's polling state, shown on the channel and in the Inbox rollup (`totals.byChannel[].email`).", "properties": { "checking": { "description": "A check holds the lease right now", "type": "boolean" }, "consecutiveFailures": { "type": "integer" }, "health": { "enum": [ "healthy", "degraded", "error" ], "type": "string" }, "lastError": { "description": "The last check's problem", "or a notice such as skipped mail; empty when clean": null, "type": "string" }, "lastPolledAt": { "format": "date-time", "type": "string" }, "nextPollAt": { "format": "date-time", "type": "string" }, "pollIntervalSeconds": { "type": "integer" }, "pushActive": { "description": "New mail arrives through Gmail push (v49); the cadence no longer matters", "type": "boolean" } }, "type": "object" }, "WorkspaceFileShare": { "additionalProperties": false, "properties": { "contentType": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "currentRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "fileId": { "pattern": "^workspace_file_[a-f0-9]{24}$", "type": "string" }, "fileRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "followLatest": { "type": "boolean" }, "id": { "pattern": "^workspace_share_[a-f0-9]{24}$", "type": "string" }, "name": { "type": "string" }, "ownerName": { "description": "Present on incoming shares; raw owner account identifiers are never exposed", "type": "string" }, "path": { "type": "string" }, "permission": { "enum": [ "read" ], "type": "string" }, "pinnedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "projectId": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" }, "recipientId": { "description": "Exact team ID for team shares; blank for direct-account shares to avoid exposing private account identifiers", "type": "string" }, "recipientName": { "description": "Anyone with the link", "or team name; private account names are never exposed": null, "public Marketplace display name": null, "type": "string" }, "recipientType": { "enum": [ "link", "user", "team" ], "type": "string" }, "revision": { "description": "Share ACL revision used for revoke CAS", "format": "int64", "minimum": 1, "type": "integer" }, "size": { "format": "int64", "minimum": 0, "type": "integer" }, "status": { "enum": [ "active", "revoked" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "fileId", "projectId", "path", "name", "contentType", "size", "recipientType", "recipientId", "permission", "followLatest", "pinnedRevision", "fileRevision", "currentRevision", "status", "revision", "createdAt", "updatedAt" ], "type": "object" }, "WorkspaceFileSharesResponse": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "nextCursor": { "description": "Opaque signed continuation cursor; absent on the final page", "maxLength": 512, "type": "string" }, "ok": { "type": "boolean" }, "share": { "$ref": "#/components/schemas/WorkspaceFileShare" }, "shareToken": { "description": "Returned exactly once when a link share is created; place it only in the client-side URL fragment and redeem it through the authenticated request body", "maxLength": 43, "minLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "shares": { "items": { "$ref": "#/components/schemas/WorkspaceFileShare" }, "maxItems": 100, "type": "array" } }, "required": [ "ok" ], "type": "object" }, "WorkspaceFileV2": { "properties": { "checksum": { "type": "string" }, "contentType": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "deletedAt": { "format": "date-time", "nullable": true, "type": "string" }, "id": { "pattern": "^workspace_file_[a-f0-9]{24}$", "type": "string" }, "indexGeneration": { "format": "int64", "type": "integer" }, "indexStatus": { "type": "string" }, "name": { "type": "string" }, "path": { "maxLength": 512, "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "size": { "format": "int64", "maximum": 53687091200, "minimum": 0, "type": "integer" }, "status": { "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "path", "name", "contentType", "size", "revision", "status", "indexStatus", "indexGeneration", "createdAt", "updatedAt" ], "type": "object" }, "WorkspaceFileV2Patch": { "properties": { "edits": { "items": { "properties": { "newText": { "type": "string" }, "oldText": { "description": "Exact unambiguous text from the original observed revision", "minLength": 1, "type": "string" } }, "required": [ "oldText", "newText" ], "type": "object" }, "maxItems": 32, "minItems": 1, "type": "array" }, "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "fileId": { "pattern": "^workspace_file_[a-f0-9]{24}$", "type": "string" }, "path": { "maxLength": 512, "type": "string" } }, "required": [ "fileId", "path", "expectedRevision", "edits" ], "type": "object" }, "WorkspaceFileV2RenameRequest": { "properties": { "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "path": { "maxLength": 512, "type": "string" }, "previousPath": { "description": "Observed original path; include to prevent concurrent rename conflicts", "type": "string" } }, "required": [ "path", "expectedRevision" ], "type": "object" }, "WorkspaceFilesV2PatchRequest": { "properties": { "changes": { "items": { "$ref": "#/components/schemas/WorkspaceFileV2Patch" }, "maxItems": 16, "minItems": 1, "type": "array" } }, "required": [ "changes" ], "type": "object" }, "WorkspaceFilesV2Response": { "properties": { "changes": { "items": { "$ref": "#/components/schemas/WorkspaceFileV2Patch" }, "type": "array" }, "error": { "type": "string" }, "file": { "$ref": "#/components/schemas/WorkspaceFileV2" }, "files": { "items": { "$ref": "#/components/schemas/WorkspaceFileV2" }, "type": "array" }, "maximumFileSize": { "format": "int64", "type": "integer" }, "nextCursor": { "type": "string" }, "ok": { "type": "boolean" }, "partSize": { "format": "int64", "type": "integer" }, "parts": { "items": { "$ref": "#/components/schemas/WorkspaceUploadPart" }, "type": "array" }, "projectId": { "type": "string" }, "status": { "type": "string" }, "upload": { "$ref": "#/components/schemas/WorkspaceUpload" } }, "required": [ "ok" ], "type": "object" }, "WorkspacePreferencesResponse": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "ok": { "type": "boolean" }, "preferences": { "additionalProperties": false, "properties": { "baseAgent": { "$ref": "#/components/schemas/WorkspaceBaseAgent" }, "generalProject": { "additionalProperties": false, "properties": { "data": { "additionalProperties": true, "type": "object" }, "description": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "description", "data" ], "type": "object" }, "ontologyContextEnabled": { "type": "boolean" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "ontologyContextEnabled", "generalProject", "baseAgent", "revision" ], "type": "object" } }, "required": [ "ok", "preferences" ], "type": "object" }, "WorkspaceProjectFamilyBatchRequest": { "additionalProperties": false, "properties": { "updates": { "description": "Project ids must be unique. The service rejects duplicate ids even when the remaining fields differ.", "items": { "$ref": "#/components/schemas/WorkspaceProjectFamilyBatchUpdate" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "updates" ], "type": "object" }, "WorkspaceProjectFamilyBatchUpdate": { "additionalProperties": false, "anyOf": [ { "required": [ "family" ] }, { "required": [ "familyNavigation" ] } ], "properties": { "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "family": { "description": "Trimmed and whitespace-normalized by the service; an empty string moves the project to Unfiled.", "maxLength": 80, "type": "string" }, "familyNavigation": { "$ref": "#/components/schemas/WorkspaceProjectFamilyNavigationPatch" }, "id": { "pattern": "^project_[a-f0-9]{24}$", "type": "string" } }, "required": [ "id", "expectedRevision" ], "type": "object" }, "WorkspaceProjectFamilyNavigationPatch": { "additionalProperties": false, "minProperties": 1, "properties": { "collapsed": { "type": "boolean" }, "order": { "maximum": 1000000000000, "minimum": -1000000000000, "type": "number" } }, "type": "object" }, "WorkspaceProjectFile": { "additionalProperties": false, "properties": { "contentType": { "maxLength": 120, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "name": { "maxLength": 120, "type": "string" }, "path": { "maxLength": 512, "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "size": { "format": "int64", "maximum": 8388608, "minimum": 0, "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "path", "name", "contentType", "size", "revision", "createdAt", "updatedAt" ], "type": "object" }, "WorkspaceProjectFilesResponse": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "file": { "$ref": "#/components/schemas/WorkspaceProjectFile" }, "files": { "items": { "$ref": "#/components/schemas/WorkspaceProjectFile" }, "type": "array" }, "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "WorkspaceProjectGroup": { "properties": { "collapsed": { "type": "boolean" }, "name": { "maxLength": 80, "type": "string" }, "order": { "type": "number" }, "revision": { "minimum": 1, "type": "integer" } }, "required": [ "name", "revision", "order", "collapsed" ], "type": "object" }, "WorkspaceProjectGroupRequest": { "additionalProperties": false, "properties": { "collapsed": { "type": "boolean" }, "expectedRevision": { "description": "Current revision for saved groups; zero for legacy inferred groups.", "minimum": 0, "type": "integer" }, "group": { "maxLength": 80, "type": "string" }, "newName": { "maxLength": 80, "type": "string" }, "operation": { "enum": [ "list", "create", "rename", "delete", "update" ], "type": "string" }, "order": { "type": "number" } }, "required": [ "operation" ], "type": "object" }, "WorkspaceProjectGroupResponse": { "properties": { "deleted": { "type": "boolean" }, "group": { "$ref": "#/components/schemas/WorkspaceProjectGroup" }, "groups": { "items": { "$ref": "#/components/schemas/WorkspaceProjectGroup" }, "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/WorkspaceWebResource" }, "type": "array" }, "ok": { "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "WorkspaceSessionContextResponse": { "additionalProperties": false, "properties": { "bytes": { "maximum": 262144, "minimum": 1, "type": "integer" }, "data": { "description": "Base64 chunk bytes", "format": "byte", "returned by context-read only": null, "type": "string" }, "digest": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "ok": { "type": "boolean" } }, "required": [ "ok", "digest", "bytes" ], "type": "object" }, "WorkspaceSessionRun": { "additionalProperties": false, "description": "A fenced execution attempt in one Session. External curl-agent runs use a 15-minute lease renewed through heartbeat; browser runs retain their existing lease. With workspaceSessionHandoff enabled, ordinary Automatic browser Sessions may continue on the server after their three-minute browser lease expires. The server attempt retains the same owner input, Agent release, saved progress and existing jobs. Its snapshot identifies continuedFromRunId and serverContinuation; the retired browser snapshot identifies serverContinuationRunId. A server-prefixed executor cannot be heartbeated, confirmed or completed by a browser. Owner cancellation remains available. Guided/native/protected controllers and approval-dependent work keep their existing recovery path. An uncertain effect requires reconciliation.", "properties": { "clientExecutorId": { "maxLength": 128, "minLength": 8, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "error": { "maxLength": 2000, "type": "string" }, "finishedAt": { "format": "date-time", "type": "string" }, "id": { "pattern": "^run_[a-f0-9]{24}$", "type": "string" }, "inputMessageId": { "pattern": "^message_[a-f0-9]{24}$", "type": "string" }, "leaseExpiresAt": { "format": "date-time", "type": "string" }, "progress": { "maxLength": 500, "type": "string" }, "sessionId": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" }, "snapshot": { "additionalProperties": true, "type": "object" }, "startedAt": { "format": "date-time", "type": "string" }, "status": { "enum": [ "queued", "running", "awaiting_confirmation", "succeeded", "failed", "cancelled", "interrupted" ], "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "sessionId", "inputMessageId", "status", "snapshot", "clientExecutorId", "leaseExpiresAt", "startedAt", "createdAt", "updatedAt" ], "type": "object" }, "WorkspaceSessionRunCreateRequest": { "additionalProperties": false, "properties": { "clientExecutorId": { "description": "Browser executor identity; server: and external: prefixes are reserved. External identities are issued by the external-agent-sessions route.", "pattern": "^[A-Za-z0-9._:-]{8,128}$", "type": "string" }, "inputMessageId": { "pattern": "^message_[a-f0-9]{24}$", "type": "string" }, "snapshot": { "additionalProperties": true, "description": "Eligible clients opt in with backgroundContinuation and save a versioned checkpoint.handoff before model/tool work. Server continuation identities, original Session data and protected boundaries are server-managed fields. Older clients without handoff checkpoints retain existing lease behavior.", "type": "object" } }, "required": [ "inputMessageId", "clientExecutorId" ], "type": "object" }, "WorkspaceSessionRunResponse": { "additionalProperties": false, "properties": { "error": { "type": "string" }, "ok": { "type": "boolean" }, "run": { "$ref": "#/components/schemas/WorkspaceSessionRun" }, "runs": { "items": { "$ref": "#/components/schemas/WorkspaceSessionRun" }, "maxItems": 100, "type": "array" } }, "required": [ "ok" ], "type": "object" }, "WorkspaceTodoWrite": { "description": "Only supplied fields change. All mutations require a stable idempotencyKey. Existing tasks require expectedRevision from a fresh read. Project and agent IDs resolve in the selected workspace. Empty strings clear optional links and dates. DELETE archives; POST restore recovers the same task.", "properties": { "agentId": { "type": "string" }, "description": { "maxLength": 12000, "type": "string" }, "dueDate": { "description": "YYYY-MM-DD calendar date, or empty", "type": "string" }, "expectedRevision": { "minimum": 1, "type": "integer" }, "fileId": { "type": "string" }, "fileRevision": { "minimum": 1, "type": "integer" }, "idempotencyKey": { "maxLength": 240, "minLength": 1, "type": "string" }, "projectId": { "type": "string" }, "sourceSessionId": { "type": "string" }, "status": { "enum": [ "todo", "in_progress", "needs_review", "done" ], "type": "string" }, "text": { "maxLength": 4000, "minLength": 1, "type": "string" }, "title": { "maxLength": 240, "minLength": 1, "type": "string" } }, "required": [ "idempotencyKey" ], "type": "object" }, "WorkspaceUpload": { "properties": { "contentType": { "type": "string" }, "expectedRevision": { "format": "int64", "minimum": 0, "type": "integer" }, "expectedSize": { "format": "int64", "minimum": 0, "type": "integer" }, "expiresAt": { "format": "date-time", "type": "string" }, "fileId": { "type": "string" }, "grant": { "description": "Private expiring credential for this upload only; never print or persist in shared files", "type": "string" }, "id": { "pattern": "^workspace_upload_[a-f0-9]{24}$", "type": "string" }, "multipartUploadId": { "type": "string" }, "partUrlTemplate": { "description": "Same-origin path ending in /parts/{partNumber}. Substitute a 1-based part number. PUT raw bytes with Origin matching the website and X-Workspace-Grant from this response. Account cookies and CSRF are not the storage-part credential.", "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "fileId", "path", "contentType", "expectedSize", "expectedRevision", "multipartUploadId", "partUrlTemplate", "grant", "expiresAt" ], "type": "object" }, "WorkspaceUploadCompleteRequest": { "properties": { "checksum": { "description": "SHA-256 hex of the entire original file. Supply this for subsequent exact text patch verification; a multipart ETag is not the whole-file SHA-256.", "type": "string" }, "parts": { "description": "All raw upload part receipts ordered consecutively from 1. Empty only for an empty file.", "items": { "$ref": "#/components/schemas/WorkspaceUploadPart" }, "maxItems": 10000, "type": "array" } }, "required": [ "parts" ], "type": "object" }, "WorkspaceUploadCreateRequest": { "properties": { "contentType": { "maxLength": 120, "type": "string" }, "expectedRevision": { "description": "Zero only for a new path; observed current revision for replacement", "format": "int64", "minimum": 0, "type": "integer" }, "path": { "description": "Relative project path without traversal", "maxLength": 512, "type": "string" }, "size": { "format": "int64", "maximum": 53687091200, "minimum": 0, "type": "integer" } }, "required": [ "path", "contentType", "size", "expectedRevision" ], "type": "object" }, "WorkspaceUploadPart": { "properties": { "etag": { "maxLength": 160, "minLength": 1, "type": "string" }, "partNumber": { "maximum": 10000, "minimum": 1, "type": "integer" } }, "required": [ "partNumber", "etag" ], "type": "object" }, "WorkspaceWebMessage": { "additionalProperties": false, "properties": { "content": { "maxLength": 65536, "minLength": 1, "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "pattern": "^message_[a-f0-9]{24}$", "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "role": { "enum": [ "system", "user", "assistant", "tool" ], "type": "string" }, "sessionId": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } }, "required": [ "id", "sessionId", "role", "content", "metadata", "createdAt" ], "type": "object" }, "WorkspaceWebMessageCreateRequest": { "additionalProperties": false, "properties": { "content": { "maxLength": 65536, "minLength": 1, "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "role": { "enum": [ "system", "user", "assistant", "tool" ], "type": "string" } }, "required": [ "role", "content" ], "type": "object" }, "WorkspaceWebResource": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "type": "string" }, "data": { "additionalProperties": true, "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "enabled": { "type": "boolean" }, "id": { "pattern": "^(project|session|wiki|skill|agent|workflow|schedule)_[a-f0-9]{24}$", "type": "string" }, "kind": { "enum": [ "project", "session", "wiki", "skill", "agent", "workflow", "schedule" ], "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "projectId": { "pattern": "^project_[a-f0-9]{24}$", "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "kind", "name", "enabled", "data", "revision", "createdAt", "updatedAt" ], "type": "object" }, "WorkspaceWebResourceWriteRequest": { "additionalProperties": false, "properties": { "data": { "additionalProperties": true, "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "enabled": { "type": "boolean" }, "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "projectId": { "pattern": "^project_[a-f0-9]{24}$", "type": "string" } }, "type": "object" }, "WorkspaceWebResponse": { "properties": { "capabilities": { "additionalProperties": true, "type": "object" }, "error": { "type": "string" }, "hasMore": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/WorkspaceWebResource" }, "items": { "items": { "$ref": "#/components/schemas/WorkspaceWebResource" }, "type": "array" }, "message": { "$ref": "#/components/schemas/WorkspaceWebMessage" }, "messages": { "items": { "$ref": "#/components/schemas/WorkspaceWebMessage" }, "type": "array" }, "nextCursor": { "type": "string" }, "ok": { "type": "boolean" }, "sessionRevision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "ok" ], "type": "object" } }, "securitySchemes": { "cookieAuth": { "description": "Log in at this website origin with sessionMode=cookie and retain both login cookies in a private curl cookie jar. The website signs backend requests; clients never need the edge signing secret. Mutations also require the matching X-CSRF-Token.", "in": "cookie", "name": "__Host-clanker_session", "type": "apiKey" } } }, "info": { "description": "Native account Workspace requests through the public website origin. Read /for-agents.md first. No browser automation or MCP connector is required. Availability and permissions remain enforced by the account and GET /v1/workspace capability contract.", "title": "Clanker Workspace HTTP API", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/v1/account": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" } }, "security": [ { "cookieAuth": [] } ], "summary": "Get the current authenticated account" } }, "/v1/apps": { "get": { "description": "Apps and their private metadata are account-owned and responses are never cacheable. Read and cleanup access remains available if hosted-app creation access is later removed.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Hosted app list and current quota" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the authenticated account's hosted apps" }, "post": { "description": "Creates private control-plane metadata only. Nothing is published until a deployment is explicitly activated. Free accounts may own at most two hosted Apps; the current account-specific allowance is returned as maxApps by the list endpoint. The hostedApps entitlement is required.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClankerAppRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Existing draft returned for an identical Idempotency-Key retry" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Private draft created" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "hostedApps entitlement required" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "App quota reached or Idempotency-Key reused with different app metadata" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a private hosted-app draft" } }, "/v1/apps/{id}": { "delete": { "description": "Writes a non-revivable public tombstone before deleting every immutable artifact. A failed cleanup remains in deletion_error and is safe to retry. Cleanup remains available if hosted-app creation access is later removed.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "App tombstoned and artifacts deleted" }, "502": { "description": "App is fenced from publication but artifact cleanup must be retried" } }, "security": [ { "cookieAuth": [] } ], "summary": "Permanently delete an owned hosted app" }, "get": { "description": "Remains available if hosted-app creation access is later removed so the owner can inspect possible public exposure.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Hosted app" }, "404": { "description": "App not found or not owned by this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read an owned hosted app" }, "parameters": [ { "$ref": "#/components/parameters/AppId" } ] }, "/v1/apps/{id}/agents": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "App agent team" } }, "security": [ { "cookieAuth": [] } ], "summary": "List reusable agents attached to an owned App" }, "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "post": { "description": "The link is reusable build context. Attaching does not copy or publish the agent, and detaching never deletes it.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Agent attached" }, "409": { "description": "App team limit reached or concurrent link conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Attach an existing account-owned agent to an App" } }, "/v1/apps/{id}/agents/{agentId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent detached" }, "409": { "description": "Link revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Detach an agent from an App without deleting the reusable agent" }, "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agent_[a-f0-9]{24}$", "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "App agent link updated" }, "409": { "description": "Link revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update an App agent link with optimistic concurrency" } }, "/v1/apps/{id}/deployments": { "get": { "description": "Remains available if hosted-app creation access is later removed so the owner can inspect retained versions.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Deployment versions and quota" } }, "security": [ { "cookieAuth": [] } ], "summary": "List immutable deployment versions for an owned app" }, "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "post": { "description": "Accepts exactly one of executable `html`, declarative `appSpec`, a bounded multi-file `staticBundle`, or an account-bound `sandboxSource` with a preflight digest. Static sandbox artifacts remain server-to-server and are written manifest-last. Executable browser code runs as supplied at the app-host origin, including browser storage, navigation, external resources, and network calls subject to ordinary browser rules. The version remains unactivated until an explicit activate call. The hostedApps entitlement is required.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClankerAppDeploymentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Existing staged deployment returned for an identical Idempotency-Key retry" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Immutable deployment staged" }, "402": { "description": "hostedApps entitlement required" }, "409": { "description": "Idempotency conflict, deletion race, ten ready/inflight versions reached, or ten retained failed versions reached. An identical retry of an existing Idempotency-Key remains allowed." }, "413": { "description": "Canonical appSpec exceeds 256 KiB or HTML exceeds 2 MiB" } }, "security": [ { "cookieAuth": [] } ], "summary": "Stage a private immutable deployment version" } }, "/v1/apps/{id}/deployments/{deploymentId}/activate": { "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/DeploymentId" } ], "post": { "description": "The only publication transition. Activation atomically advances the revisioned public route pointer; activating an earlier deployment is a rollback. Clients recovering an earlier operation can supply expectedPublishedRevision so a newer publication cannot be overwritten. Once the backend reserves a new revision, every later success or error response includes that exact publishedRevision at the top level; validation and compare-and-set failures before the increment omit it. The hostedApps entitlement is required.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "deploymentId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppPublicationPrecondition" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Deployment active at the stable public URL" }, "402": { "description": "hostedApps entitlement required" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Expected published revision changed, deletion in progress, deployment not ready, or a newer publication won after this operation reserved a revision. publishedRevision is present only in the post-reservation case." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Control-plane update or read failed. publishedRevision is present if this operation already reserved a revision." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "The app host failed after the response revision was reserved; publishedRevision identifies that exact operation." } }, "security": [ { "cookieAuth": [] } ], "summary": "Publish or roll back to an immutable deployment" } }, "/v1/apps/{id}/service-webhook": { "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "post": { "description": "The X-Clanker-App-Hook capability is scoped to an exact app, deployment and reviewed action. Reuse the same idempotencyKey for delivery retries; duplicate suppression lasts 30 days.", "parameters": [ { "in": "header", "name": "X-Clanker-App-Hook", "required": true, "schema": { "maxLength": 64, "minLength": 64, "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" }, "idempotencyKey": { "maxLength": 128, "minLength": 16, "type": "string" } }, "required": [ "data", "idempotencyKey" ], "type": "object" } } }, "required": true }, "responses": { "202": { "description": "Action queued or prior delivery receipt returned" }, "401": { "description": "Invalid or revoked capability" }, "403": { "description": "App version inactive" }, "409": { "description": "Invalid input or operation key conflict" }, "429": { "description": "App action allowance reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue one live app action using an owner-created hook token" } }, "/v1/apps/{id}/services": { "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "post": { "description": "Resolves the signed-in user, app membership, immutable deployment contract, and preview or live data boundary on the server. The owner alone manages members and enables live integration capabilities.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "deploymentId": { "type": "string" }, "operation": { "type": "string" }, "preview": { "default": false, "type": "boolean" } }, "required": [ "operation" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Scoped operation result" }, "403": { "description": "App access denied" }, "409": { "description": "Revision", "or capability conflict": null, "quota": null, "schema": null }, "429": { "description": "App request limit reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Run an authenticated app service operation or manage owned app services" } }, "/v1/apps/{id}/sources": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "App source snapshots" } }, "security": [ { "cookieAuth": [] } ], "summary": "List immutable editable source snapshots for an owned App" }, "parameters": [ { "$ref": "#/components/parameters/AppId" } ] }, "/v1/apps/{id}/sources/{sourceId}/files": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Source file metadata or exact file content" } }, "security": [ { "cookieAuth": [] } ], "summary": "List or read files from an owned immutable App source snapshot" }, "parameters": [ { "$ref": "#/components/parameters/AppId" }, { "in": "path", "name": "sourceId", "required": true, "schema": { "pattern": "^source_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "path", "required": false, "schema": { "maxLength": 512, "type": "string" } } ] }, "/v1/apps/{id}/unpublish": { "parameters": [ { "$ref": "#/components/parameters/AppId" } ], "post": { "description": "Writes an immediate no-store route tombstone. A later activation can republish any retained version. Clients recovering an earlier operation can supply expectedPublishedRevision so a newer publication cannot be removed. Once the backend reserves a new revision, every later success or error response includes that exact publishedRevision at the top level; validation and compare-and-set failures before the increment omit it. Cleanup remains available if hosted-app creation access is later removed and uses a separate global privacy circuit breaker, never the ordinary per-user publish quota.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppPublicationPrecondition" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "App unpublished" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Expected published revision changed or a newer publication won after this operation reserved a revision. publishedRevision is present only in the post-reservation case." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "Control-plane update or read failed. publishedRevision is present if this operation already reserved a revision." }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClankerAppsResponse" } } }, "description": "The app host failed after the response revision was reserved; publishedRevision identifies that exact operation." } }, "security": [ { "cookieAuth": [] } ], "summary": "Remove an app from its public URL without deleting versions" } }, "/v1/auth/login": { "post": { "description": "Public callers must use the trusted portal edge; direct API Gateway requests are rejected.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Unauthorized" } }, "security": [], "summary": "Login, optionally redeem a promo code, and return a token" } }, "/v1/auth/logout": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Logged out" } }, "security": [ { "cookieAuth": [] } ], "summary": "Revoke the current credential and clear website cookies" } }, "/v1/auth/register": { "post": { "description": "Creating an account atomically grants 2,000 compute credits ($20 at 100 credits per USD) and requires affirmative acceptance of the exact current Terms of Service and Privacy Policy version. Browser clients may request an HttpOnly cookie session. Public callers must use the trusted portal edge; direct API Gateway requests are rejected.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad request" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "User already exists" } }, "security": [], "summary": "Register a new user, grant $20 in welcome credits, optionally redeem a promo code, and return a token" } }, "/v1/auth/session": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "description": "Active session" }, "401": { "description": "Unauthorized" } }, "security": [ { "cookieAuth": [] } ], "summary": "Restore a website cookie session and its stable CSRF token" } }, "/v1/auth/session/renew": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "description": "Rotated session" } }, "security": [ { "cookieAuth": [] } ], "summary": "Extend a valid website cookie session for 30 days" } }, "/v1/credits": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditAccountResponse" } } }, "description": "Current credit balance and program values" }, "401": { "description": "Unauthorized" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read the authenticated account credit balance" } }, "/v1/llm/chat/completions": { "post": { "description": "Requires an authenticated account and X-Clanker-Cloud-Client desktop-app. Protected accounts fail closed unless their exact regional Vertex model is configured and allowlisted.", "parameters": [ { "in": "header", "name": "X-Clanker-Cloud-Client", "required": true, "schema": { "enum": [ "desktop-app" ], "type": "string" } }, { "description": "Opaque desktop run ID used to group every model call into one credit usage session.", "in": "header", "name": "X-Clanker-Billing-Session-ID", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceChatCompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Chat completion" }, "401": { "description": "Unauthorized" }, "409": { "description": "Protected inference boundary is not ready" }, "422": { "description": "Gemini accepted the request but blocked or exhausted the response before producing usable assistant text" }, "502": { "description": "The approved upstream model provider failed or returned an unclassified empty response" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a Clanker Cloud desktop chat completion" } }, "/v1/workspace": { "get": { "description": "Available to every authenticated account through the trusted workspace website edge, including accounts with no credits. Returns the browser-safe capability surface, including project-scoped resources, session navigation and pinning, agent templates/inheritance, project file tools, voice chat, the account-owned desktop relay, and confirmed arbitrary code execution in an account-owned sandbox. Hosted model execution remains credit-enforced; a Workspace voice turn is charged at 13300 basis points (1.33x) of the normal model credit charge. Direct browser computer-use APIs and DevOps remain disabled. Protected and sovereign profiles fail closed until regional workspace storage exists.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Hosted workspace capabilities" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Login required" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Protected workspace storage is not active" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read the hosted Secretary workspace capability contract" } }, "/v1/workspace/agent-improvement-budget": { "get": { "operationId": "workspaceAgentImprovementBudgetRead", "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] }, "patch": { "operationId": "workspaceAgentImprovementBudgetSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/workspace/agent-outcome-source": { "get": { "description": "Read-only versioned target. Verifies owner, session and terminal task. Specialist tasks require a retained release. Default-agent chats return reviewKind session with a source digest and no specialist release. The legacy job kind opens the owning whole-task assessment. job_result opens the individual finished job with jobId and jobDigest, including while its parent task is active. The automation kind returns a terminal hosted iteration with sourceKind and sourceDigest verified against its retained definition. No assessment or Experience is created.", "operationId": "workspaceAgentOutcomeSourceRead", "parameters": [ { "description": "message, job or run for the parent task; job_result for the individual finished job; automation for one hosted iteration", "in": "query", "name": "kind", "required": true, "schema": { "type": "string" } }, { "description": "Exact saved message, job or run identifier", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Session containing that source", "in": "query", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verified target with version, agentId, echoed source and original outcome result" }, "400": { "description": "Invalid source identifier" }, "401": { "description": "Login required" }, "404": { "description": "Source is not linked to an owned task in this session" }, "422": { "description": "Task still running or retained Agent version unavailable" }, "500": { "description": "Original task could not be verified" } }, "security": [ { "cookieAuth": [] } ], "summary": "Resolve a saved message or job to its original Agent task for review" } }, "/v1/workspace/agents/{id}/candidates": { "get": { "operationId": "workspaceAgentCandidatesList", "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "401": { "description": "Login required" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration changed or evaluation already active" }, "422": { "description": "Required test or dependency unavailable" }, "429": { "description": "Shared improvement budget exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "List proposed agent improvements" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceAgentCandidatesCreate", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "401": { "description": "Login required" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration changed or evaluation already active" }, "422": { "description": "Required test or dependency unavailable" }, "429": { "description": "Shared improvement budget exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create an instruction-only improvement candidate" } }, "/v1/workspace/agents/{id}/candidates/{candidateId}": { "get": { "operationId": "workspaceAgentCandidateDetailRead", "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "candidateId", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Saves an owned proposal revision or dismissal. Editing cancels its older queued or running comparison atomically; late results cannot overwrite the new draft. Applied versions remain immutable and further changes use a new proposal.", "operationId": "workspaceAgentCandidateDetailSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/workspace/agents/{id}/candidates/{candidateId}/promote": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "candidateId", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceAgentCandidatePromoteApply", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/workspace/agents/{id}/evaluations": { "get": { "description": "Lists owned practice, comparison and model-drafting jobs. Proposal jobs expose their original Experience revision, generated draft, explanation and usage. Automatic preparation adds a separate preparation result with a supported or needs_review decision, reason and optional semantic cases. Original work is retained separately from the candidate context; model review is never owner approval or proof of improved behavior.", "operationId": "workspaceAgentEvaluationsRead", "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "401": { "description": "Login required" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration changed or evaluation already active" }, "422": { "description": "Required test or dependency unavailable" }, "429": { "description": "Shared improvement budget exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read retained practice or evaluation evidence and job status" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "patch": { "operationId": "workspaceAgentEvaluationsCancel", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "401": { "description": "Login required" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration changed or evaluation already active" }, "422": { "description": "Required test or dependency unavailable" }, "429": { "description": "Shared improvement budget exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Cancel an owned evaluation" }, "post": { "description": "With workspacePremiumLearning support, a Premium Agent with saved private settings uses its protected publisher controller and selected private release with owner-saved simulated tool responses. No live tool action occurs. State and results identify the protected controller in runtimeVersion; publisher system messages are not stored in evaluation state. Recovery reuses settled model receipts and the original controller models. Premium model calls use the existing 10x credit rate within the requested and shared budgets; saved limits are never raised automatically. Practice trials remain ungraded and cannot qualify promotion. Private learning changes customer instructions without modifying the publisher package. Hosted and guided runtime support is separate.", "operationId": "workspaceAgentEvaluationsCreate", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "candidateId": { "description": "Optional proposal for a saved-suite comparison; must be empty for practice trials", "type": "string" }, "expectedAgentRevision": { "minimum": 1, "type": "integer" }, "expectedSuiteRevision": { "description": "Zero only with trial; otherwise the current positive saved suite revision", "minimum": 0, "type": "integer" }, "maxCredits": { "maximum": 1000, "minimum": 1, "type": "integer" }, "maxModelCalls": { "maximum": 128, "minimum": 1, "type": "integer" }, "requestKey": { "description": "Stable idempotency key; reuse the identical request after a lost response", "type": "string" }, "trial": { "description": "Owner-initiated practice input. Does not create or modify saved tests and cannot qualify promotion. Normal runtime and access checks apply.", "properties": { "fixtures": { "description": "Exact simulated tool calls; no external tool effect. Retained trial cases are limited to 96 KiB.", "items": { "properties": { "action": { "maxLength": 120, "minLength": 1, "type": "string" }, "arguments": { "description": "Exact JSON arguments matched with the action", "type": "object" }, "result": { "description": "Valid JSON value up to 16000 bytes returned by the simulation" } }, "required": [ "action", "arguments", "result" ], "type": "object" }, "maxItems": 16, "type": "array" }, "input": { "description": "Nonempty task; at most 8000 UTF-8 bytes after trimming", "maxLength": 8000, "minLength": 1, "type": "string" }, "reviewCriteria": { "description": "Optional owner review notes; at most 2000 UTF-8 bytes. Withheld from model input and never automatically graded.", "maxLength": 2000, "type": "string" } }, "required": [ "input" ], "type": "object" } }, "required": [ "requestKey", "expectedAgentRevision", "expectedSuiteRevision", "maxCredits", "maxModelCalls" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "401": { "description": "Login required" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration changed or evaluation already active" }, "422": { "description": "Required test or dependency unavailable" }, "429": { "description": "Shared improvement budget exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue a budgeted practice trial or saved-suite evaluation" } }, "/v1/workspace/agents/{id}/execution": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceAgentExecutionPrepare", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Agent execution manifest and reference" }, "409": { "description": "Changed definition or invalid continuation" }, "422": { "description": "Required dependency unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Prepare an immutable Agent release with current access checks" } }, "/v1/workspace/agents/{id}/file-checks": { "get": { "description": "Returns the original job digest, retained generated-file revisions and latest 20 owner-defined checks for currently accessible sources. No storage key or file content is returned. Files require a backend-confirmed saved receipt and a retained checksum, and are limited to 1 MiB. Larger files, older unconfirmed receipts and failed jobs are unavailable.", "operationId": "workspaceAgentFileChecksRead", "parameters": [ { "in": "query", "name": "jobId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Original files and limited file-check evidence" }, "404": { "description": "Owned source unavailable" }, "409": { "description": "Deletion or changed source" } }, "security": [ { "cookieAuth": [] } ] }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Reads the exact saved revision, verifies its bytes against its retained checksum and deterministically grades owner-defined rules. Supports file size, JSON fields/scalar equality and JSON or CSV row bounds. JSON keys are literal, duplicates are rejected, nesting is limited to 64 and finite numbers to 128 characters with exponents from -308 to 308. CSV headers must be unique and rows match header width. Checks and their evaluator/digest are immutable. Retrying a request recovers one receipt, with evidence withheld after source loss. This does not replay work, assess whole-task success, certify external effects or trigger learning or promotion. Model-selected expectedOutputs are not used as owner rules.", "operationId": "workspaceAgentFileChecksSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "checks": { "properties": { "equals": { "description": "Optional exact scalar values in a top-level JSON object", "type": "object" }, "format": { "default": "file", "enum": [ "file", "json", "csv" ], "type": "string" }, "maxRows": { "minimum": 0, "type": "integer" }, "minBytes": { "minimum": 0, "type": "integer" }, "minRows": { "minimum": 0, "type": "integer" }, "path": { "type": "string" }, "requiredKeys": { "items": { "type": "string" }, "maxItems": 32, "type": "array" } }, "required": [ "path" ], "type": "object" }, "fileId": { "type": "string" }, "fileRevision": { "minimum": 1, "type": "integer" }, "jobDigest": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "jobId": { "type": "string" }, "requestKey": { "maxLength": 128, "minLength": 8, "type": "string" } }, "required": [ "requestKey", "jobId", "jobDigest", "fileId", "fileRevision", "checks" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Immutable evidence receipt and currently accessible evidence" }, "400": { "description": "Invalid checks" }, "404": { "description": "Owned source unavailable" }, "409": { "description": "Changed source or reused request key" }, "422": { "description": "Original saved file is not checkable" }, "503": { "description": "Retry the same request after storage becomes available" } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/workspace/agents/{id}/job-outcomes": { "get": { "description": "Lists up to 20 owned finished jobs with exact retained Agent versions and result digests, including jobs whose parent task is still active. Use jobId for immutable assessment history. Job assessments are separate from parent-task assessments and monitoring samples.", "operationId": "workspaceAgentJobOutcomesRead", "parameters": [ { "description": "Last job ID from the previous results page", "in": "query", "name": "before", "schema": { "type": "string" } }, { "description": "Owned job whose assessment history should be returned", "in": "query", "name": "jobId", "schema": { "type": "string" } }, { "description": "Exclusive assessment history cursor", "in": "query", "name": "beforeRevision", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Atomically records an owner assessment and optional reviewed Experience. Stable request keys recover the original receipt alongside the current assessment. Superseding a review or changing its job result invalidates old learning evidence. Deletion removes linked lessons and history; identifier-only recovery receipts do not recreate them. This records owner judgment and does not independently certify job correctness or replay work.", "operationId": "workspaceAgentJobOutcomesSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "correction": { "maxLength": 8000, "type": "string" }, "expectedAgentRevision": { "minimum": 1, "type": "integer" }, "expectedJobDigest": { "description": "Exact job result digest returned by the read endpoint", "pattern": "^[a-f0-9]{64}$", "type": "string" }, "expectedRevision": { "minimum": 0, "type": "integer" }, "jobId": { "type": "string" }, "learn": { "default": false, "type": "boolean" }, "notes": { "maxLength": 4000, "type": "string" }, "requestKey": { "maxLength": 128, "minLength": 8, "type": "string" }, "result": { "enum": [ "success", "failure", "unknown" ], "type": "string" }, "runId": { "description": "Original parent task ID", "type": "string" }, "whenToUse": { "maxLength": 1000, "type": "string" } }, "required": [ "requestKey", "runId", "expectedAgentRevision", "expectedRevision", "result", "notes", "jobId", "expectedJobDigest" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/workspace/agents/{id}/learning": { "get": { "description": "Returns the owned agent's learning policy, up to 20 current source observations, and monitoring counts for the selected and prior tested releases. Monitoring groups repeated requests and continuations in up to 500 recent executions per release, distinguishes owner assessments from execution status, and includes the last 10 monitoring decisions. These counts do not establish causal improvement. The response includes automaticPreparation=true. Unset learning policies default to bounded auto mode under Memory; explicit saved policies are preserved. Automatic comparison requires a current owner-approved procedure or an independent model review backed by a settled receipt. When no test suite has been saved, a separate model context prepares editable semantic checks from original work; uncertainty blocks adoption. Existing suites and owner changes take precedence.", "operationId": "workspaceAgentLearningRead", "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/agents/{id}/marketplace-installation": { "get": { "description": "The detail includes privateSkills for the installation's added Skills.\nEach item contains id, name, capturedRevision, libraryRevision, available,\nand an optional unavailability message. Accessible retained instructions\nand the original Marketplace licenseId/versionId are included when present.\nCaptured content remains selected across publisher updates and rollback;\ncurrent library availability, ownership, project scope and licenses still apply.\nprivateJourney identifies an owner-edited workflow that is retained across publisher changes.\nprivateTools identifies changed tool selections or edited owned dependency copies; these stay selected unless the owner explicitly adopts publisher tools.\n", "operationId": "workspaceMarketplaceVersionGet", "responses": { "200": { "description": "Installed version and private personalization" }, "404": { "description": "Installed Agent or license not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read installed and available versions with private personalization" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "An existing added Skill keeps its captured revision unless the owner selects\nits inspected current library revision in privateSkillRevisions. A newly\nattached Skill uses its current library revision; provide the revision to\nreject concurrent edits. Selection does not rewrite the shared Skill library.\nRetrying the exact requestKey and body recovers the original operation and\nreturns current installation state. Omit the optional map when replaying an\nolder operation that did not contain it.\n", "operationId": "workspaceMarketplaceVersionSelect", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowedToolIds": { "items": { "type": "string" }, "nullable": true, "type": "array" }, "expectedAgentRevision": { "minimum": 1, "type": "integer" }, "expectedDigest": { "type": "string" }, "expectedInstallationRevision": { "minimum": 1, "type": "integer" }, "expectedPackageSchemaVersion": { "description": "Required when either the current or chosen package is executable; identifies the reviewed target package schema and prevents older servers from ignoring its runtime.", "enum": [ "clanker.marketplace.package.v1", "clanker.marketplace.package.v2", "clanker.marketplace.managed-package.v1" ], "type": "string" }, "expectedStateRevision": { "minimum": 0, "type": "integer" }, "expectedVersionId": { "type": "string" }, "licenseId": { "type": "string" }, "personalization": { "properties": { "contract": { "additionalProperties": true, "type": "object" }, "instructions": { "type": "string" }, "skillIds": { "items": { "type": "string" }, "type": "array" }, "workflowSkillIds": { "description": "Skill attachments retained automatically for a saved private workflow. Preserve the returned list when saving. Unneeded automatic attachments leave when the workflow changes; selecting a different library revision makes one an explicit private attachment.", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "privateSkillRevisions": { "additionalProperties": { "minimum": 1, "type": "integer" }, "description": "Added Skill IDs mapped to their captured or inspected current library revision. Other IDs and stale revisions are rejected.", "type": "object" }, "requestKey": { "type": "string" }, "usePublisherJourney": { "description": "Explicitly replace the current private workflow with this publisher version. Otherwise owner-edited workflows are preserved.", "type": "boolean" }, "usePublisherTools": { "description": "Explicitly select this publisher version's retained owned tool copies. Edited definitions and resources remain in the library; otherwise private tool choices are preserved.", "type": "boolean" } }, "required": [ "requestKey", "expectedAgentRevision", "expectedInstallationRevision", "expectedStateRevision", "licenseId", "expectedVersionId", "expectedDigest", "personalization" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Installed version and private personalization" }, "404": { "description": "Installed Agent or license not found" }, "409": { "description": "Stale revision or unavailable version" }, "410": { "description": "Previously updated Agent was deleted" }, "422": { "description": "Dependency or configuration unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Select an exact licensed version with private personalization" } }, "/v1/workspace/agents/{id}/marketplace-preview": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceAgentMarketplacePreview", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Private source reference and exported package preview" }, "409": { "description": "Agent revision changed" }, "422": { "description": "Required dependency or execution contract unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Review an exact retained Workspace release for publication" } }, "/v1/workspace/agents/{id}/outcomes": { "get": { "description": "Lists up to 20 owned terminal runs with their retained Agent versions and separately attributed owner assessments. Use runId for paginated immutable assessment history. Execution completion alone is not verified task success.", "operationId": "workspaceAgentOutcomesRead", "parameters": [ { "description": "Omit for Session tasks; automations lists finished hosted iterations.", "in": "query", "name": "kind", "schema": { "enum": [ "automations" ], "type": "string" } }, { "description": "Exact Session run or automationrun identifier for assessment history.", "in": "query", "name": "runId", "schema": { "type": "string" } }, { "description": "Last run ID from the previous results page", "in": "query", "name": "before", "schema": { "type": "string" } }, { "description": "Exclusive assessment history cursor", "in": "query", "name": "beforeRevision", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Atomically records an owner assessment and optional reviewed Experience. Stable request keys recover the original receipt alongside the current assessment. Superseding a review invalidates its old learning evidence without replaying work.", "operationId": "workspaceAgentOutcomesSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "correction": { "maxLength": 8000, "type": "string" }, "expectedAgentRevision": { "minimum": 1, "type": "integer" }, "expectedRevision": { "minimum": 0, "type": "integer" }, "expectedSourceDigest": { "description": "Exact original result fingerprint required with sourceKind automation.", "maxLength": 64, "minLength": 64, "type": "string" }, "learn": { "default": false, "type": "boolean" }, "notes": { "maxLength": 4000, "type": "string" }, "requestKey": { "maxLength": 128, "minLength": 8, "type": "string" }, "result": { "enum": [ "success", "failure", "unknown" ], "type": "string" }, "runId": { "type": "string" }, "sourceKind": { "description": "Required for hosted iterations; omitted for Session tasks.", "enum": [ "automation" ], "type": "string" }, "whenToUse": { "maxLength": 1000, "type": "string" } }, "required": [ "requestKey", "runId", "expectedAgentRevision", "expectedRevision", "result", "notes" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid configuration" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration or evidence changed" }, "422": { "description": "Required evaluation evidence is missing" } }, "security": [ { "cookieAuth": [] } ] } }, "/v1/workspace/agents/{id}/releases": { "get": { "operationId": "workspaceAgentReleasesList", "responses": { "200": { "description": "Agent releases" } }, "security": [ { "cookieAuth": [] } ], "summary": "List immutable Agent releases and the selected version" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceAgentReleaseSelect", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Selected release" }, "409": { "description": "Stale definition or selection" }, "422": { "description": "Required dependency unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create or select a complete Agent release for future work" } }, "/v1/workspace/agents/{id}/shares": { "get": { "responses": { "200": { "description": "Active-first Agent share records; bearer tokens are never returned by listing" } }, "security": [ { "cookieAuth": [] } ], "summary": "List owner-managed links and review the complete attached Skill package" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^agent_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Captures the exact Agent definition and confirmed attached Skill dependencies while excluding project membership, reference files, connections, secrets, loops, API publication, and Marketplace license data. Imported Agents default to approval mode. Marketplace Agents cannot be reshared outside their license.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "sharedSkillsDigest": { "description": "Digest returned by the skill review; required when skills are included", "pattern": "^[a-f0-9]{64}$", "type": "string" } }, "required": [ "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Immutable Agent definition link created" }, "409": { "already has an active link": null, "description": "Agent changed", "or cannot be reshared": null }, "429": { "description": "Private share creation rate limited" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create an account-gated snapshot link for one Agent" } }, "/v1/workspace/agents/{id}/shares/{shareId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Agent link revoked; recipient-owned copies already claimed remain independent" }, "409": { "description": "Agent share changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Revoke an account-gated Agent link at an exact share revision" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^agent_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "shareId", "required": true, "schema": { "pattern": "^workspace_resource_share_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ] }, "/v1/workspace/agents/{id}/test-suite": { "get": { "description": "Owners can edit criteria and proposed improvements. Automatically prepared suites include origin=model and generationId; owner saves create a new revision with origin=owner and preserve the original version. No existing suite, including an explicitly empty suite, is replaced automatically. Comparisons with rubric checks retain the semantic evaluator version, independent review receipts, explanations and source references. Unknown cases do not become regression or improvement samples and leave the proposal open for review. Each reviewed answer consumes an additional call within the saved comparison/daily budget.", "operationId": "workspaceAgentTestSuiteRead", "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "401": { "description": "Login required" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration changed or evaluation already active" }, "422": { "description": "Required test or dependency unavailable" }, "429": { "description": "Shared improvement budget exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Saved editable test suite" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "put": { "description": "With workspaceAgentSemanticEvaluation support, checks can use kind rubric and a natural-language criterion in value. Each answer receives an independent model review with pass, fail, or unknown and evidence references. Literal text/tool/JSON checks remain available for explicit requirements. Existing saved checks and evaluation receipts keep their original semantics.", "operationId": "workspaceAgentTestSuiteSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "description": "Invalid request" }, "401": { "description": "Login required" }, "404": { "description": "Owned agent or record not found" }, "409": { "description": "Configuration changed or evaluation already active" }, "422": { "description": "Required test or dependency unavailable" }, "429": { "description": "Shared improvement budget exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Save an owner-revision-fenced test suite" } }, "/v1/workspace/agents/{id}/versions": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgentVersionsResponse" } } }, "description": "Newest-first Agent versions, capped at 25" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid Agent id" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Agent not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the authenticated account's bounded saved history for one Workspace Agent" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^agent_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/agents/{id}/versions/{revision}/restore": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^agent_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "post": { "description": "Requires the exact current revision. Marketplace-origin Agents cannot be restored, even if their mutable Agent data was later edited. Restoring a disabled snapshot applies the existing Agent-disable lifecycle; restores never restart loops.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgentRestoreRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgentVersionsResponse" } } }, "description": "Historical settings restored as a new current Agent revision" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid Agent id, version, or expectedRevision body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Agent or requested version not found in this account" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Revision conflict, Marketplace-origin Agent, tag conflict, or stale project scope" } }, "security": [ { "cookieAuth": [] } ], "summary": "Restore a personal Workspace Agent snapshot as a new revision" } }, "/v1/workspace/agents:readiness": { "post": { "operationId": "workspaceAgentReadiness", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "agentId": { "type": "string" }, "definition": { "description": "Editable Agent fields; required for draft, forbidden for selected", "type": "object" }, "expectedAgentRevision": { "description": "Zero for a new draft; current revision for a saved Agent", "minimum": 0, "type": "integer" }, "projectId": { "type": "string" }, "requestKey": { "maxLength": 100, "type": "string" }, "source": { "enum": [ "draft", "selected" ], "type": "string" } }, "required": [ "source" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Versioned readiness, dependency identities, runtime coverage and memory preference with its Workspace preference revision" }, "400": { "description": "Invalid inspection request" }, "404": { "description": "Agent not found" }, "409": { "description": "Agent revision changed" }, "500": { "description": "Setup could not be verified" } }, "security": [ { "cookieAuth": [] } ], "summary": "Inspect a draft or selected Agent without saving or executing it" } }, "/v1/workspace/agents:save": { "post": { "operationId": "workspaceAgentBuilderSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Saved Agent, jobs and idempotent receipt" }, "400": { "description": "Invalid configuration" }, "409": { "description": "Stale revision or conflicting save key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Atomically save an Agent and its recurring jobs" } }, "/v1/workspace/app-builds": { "get": { "parameters": [ { "in": "query", "name": "appId", "required": false, "schema": { "pattern": "^app_[a-f0-9]{20,64}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAppBuildResponse" } } }, "description": "Recent App builds" } }, "security": [ { "cookieAuth": [] } ], "summary": "List durable account-owned Workspace App builds" }, "post": { "description": "Runs an adaptive filesystem-native Builder with the exact selected Agent and Skill context, lets it choose and revise any browser-deliverable implementation inside an isolated sandbox, repairs from tool evidence and fresh recovery episodes, then stages the finalized artifact as a private App version. Managed-model access is available only when the authenticated owner explicitly sets managedModelAllowed, and the finalized artifact must match its frozen capability declaration. Runtime evaluation is advisory; account boundaries, sandbox isolation, credits, artifact identity, and publication remain deterministic. This route never grants computer use or DevOps access and never publishes the App.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAppBuildCreateRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAppBuildResponse" } } }, "description": "App build queued" }, "409": { "description": "An App build is already active or the account concurrency limit was reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue a durable, isolated Workspace App build" } }, "/v1/workspace/app-builds/{buildId}": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAppBuildResponse" } } }, "description": "App build" }, "404": { "description": "App build not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one durable Workspace App build" }, "parameters": [ { "in": "path", "name": "buildId", "required": true, "schema": { "pattern": "^build_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/app-builds/{buildId}/{action}": { "get": { "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAppBuildResponse" } } }, "description": "App build events when action is events" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read append-only progress events for one App build" }, "parameters": [ { "in": "path", "name": "buildId", "required": true, "schema": { "pattern": "^build_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "events", "cancel", "retry" ], "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAppBuildResponse" } } }, "description": "Updated App build" } }, "security": [ { "cookieAuth": [] } ], "summary": "Cancel or retry one durable App build" } }, "/v1/workspace/apps/{id}/shares": { "get": { "responses": { "200": { "description": "Active-first App share records; bearer tokens are never returned by listing" } }, "security": [ { "cookieAuth": [] } ], "summary": "List owner-managed account-gated links for one App" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^app_[a-f0-9]{20,64}$", "type": "string" } } ], "post": { "description": "Grants access to one immutable deployment. App source, project membership, attached Agents, connections, secrets, build history, publishing controls, and Marketplace controls remain private.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "deploymentId": { "pattern": "^deploy_[a-f0-9]{20,64}$", "type": "string" }, "expectedContentDigest": { "pattern": "^[a-f0-9]{64}$", "type": "string" } }, "required": [ "deploymentId", "expectedContentDigest" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Exact App version link created" }, "409": { "description": "App version changed or already has an active link" }, "429": { "description": "Private share creation rate limited" } }, "security": [ { "cookieAuth": [] } ], "summary": "Share one exact runnable App version behind a Clanker Cloud account gate" } }, "/v1/workspace/apps/{id}/shares/{shareId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "App access revoked; already-issued preview URLs expire within five minutes" }, "409": { "description": "App share changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Revoke account-gated access to an App version" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^app_[a-f0-9]{20,64}$", "type": "string" } }, { "in": "path", "name": "shareId", "required": true, "schema": { "pattern": "^workspace_resource_share_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ] }, "/v1/workspace/automations": { "get": { "parameters": [ { "in": "query", "name": "kind", "required": false, "schema": { "enum": [ "loop", "schedule" ], "type": "string" } }, { "description": "Return only loops contained by this exact account-owned agent.", "in": "query", "name": "ownerAgentId", "required": false, "schema": { "pattern": "^agent_[a-f0-9]{24}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Account-owned hosted automations" } }, "security": [ { "cookieAuth": [] } ], "summary": "List durable hosted Workspace loops or schedules" }, "post": { "description": "Hosted iterations checkpoint model messages, tool receipts, budgets, and operation IDs between deliveries. schedule.execution.allowComputerJobs defaults to false and requires owner opt-in for unattended scripts and commands. Jobs use the dedicated worker session and stable per-step idempotency; the next iteration waits for terminal job evidence. Each iteration permits up to 64 tool calls and two hours including computer time; each computer job permits up to 3600 seconds. Computer usage is billed separately from the server-enforced 10x loop inference multiplier. Assigned Agent capabilities and autonomy apply. Selected connections allow read-only tools with current revisions only. Writes use versioned project storage under loops/{automationId}/ with quotas and optimistic revision checks. Deleting a loop or its worker while work is active returns a conflict; stop and wait first. Selected custom Tools use app.run_tool with exact toolId/version/input, a server-bound automationRunId, and a durable custom_tool operation receipt. Original and current Automatic Agent behavior and unattended-compute permission are required. Nested tool and model calls share iteration limits and its inference multiplier. The server awaits terminal evidence, recovers the original request after lost acknowledgements, and propagates cancellation.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Automation created" }, "400": { "description": "Invalid schedule or account-owned reference" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a hosted Workspace loop or schedule with a dedicated durable worker session" } }, "/v1/workspace/automations/{automationId}": { "delete": { "parameters": [ { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Deleted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete one hosted Workspace automation and its dedicated worker history" }, "get": { "responses": { "200": { "description": "Automation" }, "404": { "description": "Automation not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one hosted Workspace automation" }, "parameters": [ { "in": "path", "name": "automationId", "required": true, "schema": { "pattern": "^schedule_[a-f0-9]{24}$", "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Updated automation" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update one hosted Workspace automation using optimistic concurrency" } }, "/v1/workspace/automations/{automationId}/commands": { "parameters": [ { "in": "path", "name": "automationId", "required": true, "schema": { "pattern": "^schedule_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "command": { "enum": [ "stop", "resume", "reset_context", "context", "compute" ], "type": "string" }, "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "immediate": { "type": "boolean" }, "mode": { "type": "string" }, "reason": { "maxLength": 1000, "type": "string" } }, "required": [ "command" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Updated loop lifecycle" }, "409": { "description": "Loop revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Stop, resume, reset context, or change loop context and compute controls" } }, "/v1/workspace/automations/{automationId}/documents": { "get": { "responses": { "200": { "description": "Current documents and revisions" }, "404": { "description": "Loop not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read the human-editable LOOP.md and STATE.md documents for one loop" }, "parameters": [ { "in": "path", "name": "automationId", "required": true, "schema": { "pattern": "^schedule_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/automations/{automationId}/documents/{documentName}": { "get": { "responses": { "200": { "description": "Document content and revision" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one human-editable loop document" }, "parameters": [ { "in": "path", "name": "automationId", "required": true, "schema": { "pattern": "^schedule_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "documentName", "required": true, "schema": { "enum": [ "loop", "state" ], "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "description": "LOOP.md accepts 32 KiB; STATE.md is capped at 16 KiB.", "maxLength": 32768, "type": "string" }, "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "content", "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Updated document and loop" }, "409": { "description": "Document revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Revision-fence an owner edit to LOOP.md or STATE.md" } }, "/v1/workspace/automations/{automationId}/documents/{documentName}/versions": { "get": { "responses": { "200": { "description": "Recent human-readable document versions" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the bounded recovery history for LOOP.md or STATE.md" }, "parameters": [ { "in": "path", "name": "automationId", "required": true, "schema": { "pattern": "^schedule_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "documentName", "required": true, "schema": { "enum": [ "loop", "state" ], "type": "string" } } ] }, "/v1/workspace/automations/{automationId}/runs/{runId}/recovery": { "get": { "description": "Returns an evidence digest, recorded execution deadline, available tool receipts and any later terminal receipt. canClose requires the original active child with an expired persisted deadline. Older executions without that boundary and missing or conflicting bindings cannot be closed by elapsed-time inference. Recovery inspection does not execute any work.", "responses": { "200": { "description": "Current owned execution evidence and review availability" }, "404": { "description": "Owned source is unavailable" }, "409": { "description": "Original recovery identity or binding is unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Inspect the original Premium execution receipts and saved owner recovery review" }, "parameters": [ { "in": "path", "name": "automationId", "required": true, "schema": { "pattern": "^schedule_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "runId", "required": true, "schema": { "pattern": "^automationrun_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Requires the exact digest returned by inspection and an acknowledgement that already-sent effects were reviewed. Atomically closes the missing receipt as failed with unverified task outcome and pauses the automation. No execution is replayed. Repeating the same requestKey and complete body recovers the original review; changed receipts or settings conflict. Late receipts remain inspectable without changing the owner's review or resuming the schedule. Requires workspacePremiumRecovery support.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "effectsReviewed": { "enum": [ true ], "type": "boolean" }, "expectedDigest": { "maxLength": 64, "minLength": 64, "type": "string" }, "notes": { "maxLength": 4000, "minLength": 1, "type": "string" }, "requestKey": { "pattern": "^[a-zA-Z0-9_-]{16,100}$", "type": "string" } }, "required": [ "requestKey", "expectedDigest", "notes", "effectsReviewed" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Saved review or original acknowledgement with current receipts" }, "400": { "description": "Review details or acknowledgement are missing" }, "404": { "description": "Owned source is unavailable" }, "409": { "description": "Execution remains active or evidence and settings changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Record owner review of an expired Premium execution and pause future work" } }, "/v1/workspace/automations/{automationId}/{action}": { "get": { "description": "New runs include configuration metadata with the immutable definition digest, automationRevision and optional exact agentRelease reference. Premium hosted jobs additionally identify configuration.runtime as marketplace. Older runs may omit configuration. Private definition contents are not included in this response. A completed run with definitionConflict kept its original result and proposed state without applying them to a newer edited loop definition.", "responses": { "200": { "description": "Recent automation runs" } }, "security": [ { "cookieAuth": [] } ], "summary": "List durable run history when action is runs" }, "parameters": [ { "in": "path", "name": "automationId", "required": true, "schema": { "pattern": "^schedule_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "run", "runs" ], "type": "string" } } ], "post": { "description": "Admission atomically retains the current job definition, agent release, loop and state documents, configured model and compute choices, context settings and selected connections. Edits and new grants apply to future runs; current revocations still constrain admitted work. Scheduled runs use the same admission snapshot contract. With workspacePremiumHosted support, Premium agents with saved private settings use one durable Marketplace run at the existing Premium rate. The protected runtime chooses its models; local job model and compute overrides do not replace them. Cancellation waits for a terminal child receipt. Missing or uncertain receipts remain active for review and never authorize implicit replay.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "and project artifacts.": null, "description": "Run queued; the completed run result records its completed or blocked outcome", "state revision": null, "tool-call summaries": null }, "409": { "description": "An execution is already active" } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue an immediate hosted execution when action is run" } }, "/v1/workspace/browser-sessions": { "get": { "description": "Available only through the signed workspace.clankercloud.ai edge.", "responses": { "200": { "description": "Cloud browser session list" } }, "security": [ { "cookieAuth": [] } ], "summary": "List recent account-owned Cloud browser sessions" }, "post": { "description": "Starts a one-account isolated browser credit session at 1 Clanker credit per active minute. The backend returns an edge-only dispatch that is never exposed to the browser client.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Cloud browser session prepared" }, "402": { "description": "Credits unavailable" }, "409": { "description": "Another Cloud browser session is active" } }, "security": [ { "cookieAuth": [] } ], "summary": "Start an isolated metered Cloud browser session" } }, "/v1/workspace/browser-sessions/{browserSessionId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Cloud browser stopped" } }, "security": [ { "cookieAuth": [] } ], "summary": "Stop an account-owned Cloud browser session" }, "get": { "responses": { "200": { "description": "Cloud browser session" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read an account-owned Cloud browser session" }, "parameters": [ { "in": "path", "name": "browserSessionId", "required": true, "schema": { "pattern": "^browser_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/browser-sessions/{browserSessionId}/actions": { "parameters": [ { "in": "path", "name": "browserSessionId", "required": true, "schema": { "pattern": "^browser_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Secret actions require an exact session allowlist, Agent binding, usage mode, and current origin. Plaintext values are returned only in the signed edge dispatch and never in the client response.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Edge-only browser action dispatch" }, "403": { "description": "Browser or Secret policy denied the action" } }, "security": [ { "cookieAuth": [] } ], "summary": "Authorize one Cloud browser action for the trusted Workspace edge" } }, "/v1/workspace/browser-sessions/{browserSessionId}/close": { "parameters": [ { "in": "path", "name": "browserSessionId", "required": true, "schema": { "pattern": "^browser_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Cloud browser session closed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Close a Cloud browser session and finalize metered browser credits" } }, "/v1/workspace/channels": { "get": { "responses": { "200": { "description": "Account-owned channel connections" } }, "security": [ { "cookieAuth": [] } ], "summary": "List connected external messaging channels" }, "post": { "description": "The platform credential is validated live, sealed per channel, and never returned. The webhook URL, webhook secret, and Meta verify token appear only in this response. Viber webhooks are registered programmatically; WhatsApp channels stay pending until Meta's webhook verification succeeds.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Channel created with one-time webhook secrets" }, "400": { "credential shape": null, "description": "Invalid platform", "or binding": null }, "409": { "description": "Channel limit reached or platform account already connected" }, "422": { "description": "The platform rejected the credential" } }, "security": [ { "cookieAuth": [] } ], "summary": "Connect an external messaging channel (WhatsApp Cloud API or Viber bot)" } }, "/v1/workspace/channels/chats:batch": { "post": { "description": "Uniform bulk action (read, unread, star, unstar, archive, unarchive, label, unlabel, priority, move, assign, run, delegate) with per-item results. delegate forwards each conversation to agentId with an optional task brief — a selection spanning one bad chat must not abort the rest.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Per-item results" }, "400": { "description": "Invalid action", "no duplicates)": null, "or batch bounds (1-100": null, "parameters": null } }, "security": [ { "cookieAuth": [] } ], "summary": "One action over 1-100 conversations" } }, "/v1/workspace/channels/email:discover": { "post": { "description": "Walks a preset table, MX records, RFC 6186 SRV, Thunderbird autoconfig, and hostname guesses. With verify=true, proves each candidate with a real login and returns the first that works. The password is used only to verify and is never echoed back.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Discovery result (ok=false with an error when nothing was found or verification failed)" }, "400": { "description": "Missing email", "or verify requested without a password": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Discover IMAP/SMTP settings for an email address" } }, "/v1/workspace/channels/inbox": { "get": { "description": "Every non-archived chat across the account's channels, newest activity first, with unread/needs-attention state, the email subject, the WhatsApp service window, and a last-message preview. Keyset-paginated; totals include per-channel unread counts for folder badges.", "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "channelId", "required": false, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "agentId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "projectId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "platform", "required": false, "schema": { "enum": [ "whatsapp", "viber", "whatsapp_bridge", "email" ], "type": "string" } }, { "in": "query", "name": "chatStatus", "required": false, "schema": { "enum": [ "unbound", "active", "paused", "archived" ], "type": "string" } }, { "in": "query", "name": "unread", "required": false, "schema": { "enum": [ "true" ], "type": "string" } }, { "in": "query", "name": "attention", "required": false, "schema": { "enum": [ "true" ], "type": "string" } }, { "description": "Chat-level match against sender/display name and last email subject.", "in": "query", "name": "q", "required": false, "schema": { "maxLength": 256, "type": "string" } }, { "in": "query", "name": "starred", "required": false, "schema": { "enum": [ "true" ], "type": "string" } }, { "in": "query", "name": "priority", "required": false, "schema": { "enum": [ "none", "low", "high" ], "type": "string" } }, { "in": "query", "name": "label", "required": false, "schema": { "pattern": "^chlabel_[a-f0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "Inbox page with nextCursor and totals" }, "400": { "cursor": null, "description": "Invalid limit", "or filter parameter": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Aggregate conversation inbox across every connected channel" } }, "/v1/workspace/channels/inbox/badge": { "get": { "description": "The three numbers the shell shows (unread conversations, conversations needing attention, drafts awaiting approval) from one query, cached per viewer for 30 seconds (v52). Prefer this over polling the inbox with limit=1.", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "attentionChats": { "type": "integer" }, "changedAt": { "description": "When any conversation last changed; a cheap anything-new check", "format": "date-time", "type": "string" }, "pendingDrafts": { "type": "integer" }, "unreadChats": { "type": "integer" } }, "type": "object" } } }, "description": "Counts" } }, "security": [ { "cookieAuth": [] } ], "summary": "Counts for the nav badge" } }, "/v1/workspace/channels/inbox/search": { "get": { "description": "Searches message content plus sender and subject identity, grouped by conversation with up to three hits each. Supports Gmail-style operators (from:, subject:, has:attachment, is:unread, before:, after:) mixed with free text. Conversation-level keyset pagination with the inbox cursor.", "parameters": [ { "in": "query", "name": "q", "required": true, "schema": { "maxLength": 256, "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 50, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "channelId", "required": false, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "agentId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "projectId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results grouped by conversation", "with nextCursor": null }, "400": { "cursor": null, "description": "Missing or invalid q", "limit": null, "or filter": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Deep search across channel conversations" } }, "/v1/workspace/channels/labels": { "get": { "responses": { "200": { "description": "Labels ordered by position then name" } }, "security": [ { "cookieAuth": [] } ], "summary": "List conversation labels (virtual folders)" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Created label" }, "400": { "description": "Invalid name or label limit reached" }, "409": { "description": "A label with this name already exists" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a conversation label" } }, "/v1/workspace/channels/labels/{labelId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Label not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete a label; conversation memberships cascade" }, "parameters": [ { "in": "path", "name": "labelId", "required": true, "schema": { "pattern": "^chlabel_[a-f0-9]+$", "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Updated label" }, "409": { "description": "Revision conflict or duplicate name" } }, "security": [ { "cookieAuth": [] } ], "summary": "Rename, recolor, or reposition a label (revision CAS)" } }, "/v1/workspace/channels/notifications": { "get": { "description": "Mentions, assignments, handoffs, and agent escalations addressed to the calling workspace member. unread=1 narrows to unread. Includes the unread count for the nav badge.", "parameters": [ { "in": "query", "name": "unread", "required": false, "schema": { "enum": [ "1" ], "type": "string" } } ], "responses": { "200": { "description": "Notifications with an unread count" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the caller's channel notifications" } }, "/v1/workspace/channels/notifications:read": { "post": { "description": "Marks the caller's notifications read. An empty ids list marks all. Scoped to the calling member - one teammate cannot clear another's badge.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ids": { "items": { "type": "integer" }, "type": "array" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Marked read" } }, "security": [ { "cookieAuth": [] } ], "summary": "Mark channel notifications read" } }, "/v1/workspace/channels/oauth/microsoft/callback": { "get": { "description": "Exchanges the code (PKCE), verifies IMAP and SMTP with XOAUTH2, creates or reconnects the email channel, and redirects to", "responses": { "302": { "description": "Redirect back to the Channels page" } }, "security": [ { "cookieAuth": [] } ], "summary": "Complete Microsoft mailbox sign-in" } }, "/v1/workspace/channels/oauth/{provider}/start": { "post": { "description": "Seals the wizard's channel settings (name, default agent, conversation home, check interval, or channelId to reconnect) in a user-bound state cookie and returns the provider's authorization URL. The callback creates or reconnects the channel and redirects to", "parameters": [ { "in": "path", "name": "provider", "required": true, "schema": { "enum": [ "google", "microsoft" ], "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Authorization URL" }, "400": { "description": "Invalid channel settings" }, "503": { "description": "The provider's sign-in is not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Start \"Sign in with Google / Microsoft\" for an email channel" } }, "/v1/workspace/channels/project-email/{channelId}": { "delete": { "operationId": "WorkspaceProjectEmailDelete", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedRevision": { "minimum": 1, "type": "integer" } }, "required": [ "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Deleted" }, "409": { "description": "The email address revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete a managed email address while preserving conversations" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/channels/project-email/{channelId}/rename": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "WorkspaceProjectEmailRename", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedRevision": { "minimum": 1, "type": "integer" }, "localPart": { "maxLength": 48, "minLength": 1, "type": "string" } }, "required": [ "localPart", "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Renamed" }, "409": { "description": "The email address revision changed or name is unavailable" }, "503": { "description": "New address reserved but setup needs a retry" } }, "security": [ { "cookieAuth": [] } ], "summary": "Rename or retry setup for a managed email address" } }, "/v1/workspace/channels/receipts:summary": { "get": { "description": "Daily buckets of sent/delivered/read plus read rate and median time-to-read, over a window (days 1-90). channelId narrows to one channel; agentId resolves the effective agent (chat binding, else channel default).", "parameters": [ { "in": "query", "name": "channelId", "required": false, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "agentId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "days", "required": false, "schema": { "default": 7, "maximum": 90, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "Summary with per-day buckets" }, "400": { "agentId": null, "description": "Invalid channelId", "or days": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Delivery/read analytics over outbound receipts" } }, "/v1/workspace/channels/rules": { "get": { "responses": { "200": { "description": "Rules ordered by position" } }, "security": [ { "cookieAuth": [] } ], "summary": "List channel rules" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Created" }, "400": { "bounds": null, "description": "Invalid rule (unknown field/op/action", "or limit reached)": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a channel rule" } }, "/v1/workspace/channels/rules/{ruleId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Rule not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete a channel rule" }, "parameters": [ { "in": "path", "name": "ruleId", "required": true, "schema": { "pattern": "^chrule_[A-Za-z0-9]{16}$", "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Updated" }, "400": { "description": "Invalid patch or missing expectedRevision" }, "409": { "description": "Revision conflict or rule not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update a channel rule (optimistic concurrency via expectedRevision)" } }, "/v1/workspace/channels/{channelId}": { "delete": { "parameters": [ { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Deleted" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Disconnect a channel, retiring its responders while keeping chat transcripts" }, "get": { "responses": { "200": { "description": "Channel" }, "404": { "description": "Channel not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one channel connection" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Updated channel" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update channel defaults, reply policy, enabled status, or the channel-wide instructions every agent follows" } }, "/v1/workspace/channels/{channelId}/agents": { "delete": { "parameters": [ { "in": "query", "name": "agentId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Removed" }, "404": { "description": "Channel or roster entry not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Remove an agent from the roster" }, "get": { "description": "The agents staffing this channel with role (one lead per channel), position, per-channel instructions, and enabled state. Staffing only - external-send permission remains with the grants route.", "responses": { "200": { "description": "The channel's roster" }, "404": { "description": "Channel not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the channel's agent roster" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "put": { "description": "Upserts an agent's role (lead|specialist), position, per-channel instructions (max 4096 chars), and enabled state. Promoting a second lead returns 409 - demote the incumbent first.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "agentId": { "minLength": 1, "type": "string" }, "enabled": { "type": "boolean" }, "instructions": { "maxLength": 4096, "type": "string" }, "position": { "type": "integer" }, "role": { "enum": [ "lead", "specialist" ], "type": "string" } }, "required": [ "agentId", "role" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Roster updated" }, "400": { "description": "Invalid agent id", "or oversized instructions": null, "role": null }, "404": { "description": "Channel not found" }, "409": { "description": "The channel already has a lead" } }, "security": [ { "cookieAuth": [] } ], "summary": "Add or update a roster entry" } }, "/v1/workspace/channels/{channelId}/audit": { "get": { "description": "Newest first. Every grant change, external send, draft decision, blocked send, escalation, delegation, assignment and state change. Continue with before=\u003clast id\u003e.", "parameters": [ { "in": "query", "name": "before", "required": false, "schema": { "minimum": 1, "type": "integer" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "Ledger entries" }, "404": { "description": "Channel not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Page the channel's send-audit ledger (owner/admin)" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/channels/{channelId}/chats": { "get": { "parameters": [ { "description": "One conversation by its platform id (v51); `chats` holds it or is empty.", "in": "query", "name": "externalChatId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chats with session and responder bindings" } }, "security": [ { "cookieAuth": [] } ], "summary": "List external conversations on a channel" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "patch": { "description": "Platform chat identifiers may contain URL-hostile characters, so the target chat travels in the request body. Binding an agent to a chat with buffered inbound messages triggers an immediate responder run.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "properties": { "externalChatId": { "minLength": 1, "type": "string" } }, "required": [ "externalChatId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Updated chat" }, "404": { "description": "Chat not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Bind an agent or update one chat, addressed by externalChatId in the body" } }, "/v1/workspace/channels/{channelId}/chats/assign": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Sets (or clears, with an empty assigneeActorId) the human owner of a conversation. The assignee must be an active member. pauseAgent additionally pauses the agent - the \"I'm taking this over\" gesture. Notifies the assignee.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "assigneeActorId": { "type": "string" }, "externalChatId": { "minLength": 1, "type": "string" }, "pauseAgent": { "type": "boolean" } }, "required": [ "externalChatId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Assignment updated", "returns the chat": null }, "400": { "description": "Assignee is not an active member" }, "404": { "description": "Chat not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Assign a conversation to a workspace member" } }, "/v1/workspace/channels/{channelId}/chats/forward": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Provisions the agent as a participant on the shared session (it sees the full thread), records an internal note with the operator's context, and triggers the agent's run. Internal-only - the agent's output is governed by its own external-send grant.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "agentId": { "minLength": 1, "type": "string" }, "externalChatId": { "minLength": 1, "type": "string" }, "note": { "type": "string" } }, "required": [ "externalChatId", "agentId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Forwarded", "with the internal note's message id": null }, "400": { "description": "Agent is not an enabled member of the roster" }, "404": { "description": "Channel or chat not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Forward a conversation to a rostered agent" } }, "/v1/workspace/channels/{channelId}/chats/handoff": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Assigns the conversation, appends an internal context note (never sent externally), notifies the assignee, and writes an escalation audit row. pauseAgent optionally pauses the agent.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "assigneeActorId": { "minLength": 1, "type": "string" }, "externalChatId": { "minLength": 1, "type": "string" }, "note": { "type": "string" }, "pauseAgent": { "type": "boolean" } }, "required": [ "externalChatId", "assigneeActorId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Handed off", "with the internal note's message id": null }, "400": { "description": "Assignee is not an active member" }, "404": { "description": "Chat not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Hand a conversation to a teammate with context" } }, "/v1/workspace/channels/{channelId}/chats/messages": { "get": { "description": "Same pages as the session history (limit, before, messageId). Authorized by channel access, so organization members operating a team-linked channel can read its conversations without session access.", "parameters": [ { "in": "query", "name": "externalChatId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "schema": { "maximum": 200, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "before", "schema": { "type": "string" } }, { "description": "Messages strictly newer than this id, oldest first (v52); for incremental polling. Exclusive with before and messageId.", "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "messageId", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of the transcript" }, "404": { "description": "Chat not found or outside the caller's channels" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one conversation's transcript through the channel" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/channels/{channelId}/chats/notes": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Writes an internal note into the conversation transcript, addressed by externalChatId. Internal notes are team/agent coordination only and are never delivered to the external contact - this route contains no send path. Optional agentIds (owner/admin, at most 3) forward the conversation to those rostered agents with the note as their brief; results come back per agent under routed.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "maxLength": 8000, "minLength": 1, "type": "string" }, "externalChatId": { "minLength": 1, "type": "string" } }, "required": [ "externalChatId", "content" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Internal note appended", "with its message id": null }, "404": { "description": "Chat not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Append a team-only internal note to one conversation (never sent externally)" } }, "/v1/workspace/channels/{channelId}/chats/presence": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Advisory only - upserts the caller's viewing/typing state and returns the other members currently live on the conversation, so the composer can warn before a double reply. The at-most-once send claims remain the correctness backstop.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "externalChatId": { "minLength": 1, "type": "string" }, "state": { "enum": [ "viewing", "typing" ], "type": "string" } }, "required": [ "externalChatId", "state" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Heartbeat recorded", "returns live peers": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Presence heartbeat for a conversation" } }, "/v1/workspace/channels/{channelId}/chats/read": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "read=true zeroes the unread and needs-attention counters and sets the read watermark; read=false resets both watermarks so the conversation visibly returns to unread even after an agent run covered it. Idempotent.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "externalChatId": { "minLength": 1, "type": "string" }, "read": { "type": "boolean" } }, "required": [ "externalChatId", "read" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Updated chat with its unread state" }, "404": { "description": "Chat not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Mark one chat read or unread, addressed by externalChatId in the body" } }, "/v1/workspace/channels/{channelId}/chats/reply": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Sends as the workspace owner - threaded SMTP without the Auto-Submitted marker for email, platform sends for WhatsApp/Viber. The reply allowlist, autoReply toggle, and the agent's hourly email budget do not apply; a dedicated operator rate limit and the optional clientDedupeKey provide at-most-once delivery. Replying marks the conversation read.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Workspace files to send with the message (email only). Each is resolved from the caller's own storage, must be an allowed document or image type, at most 10 MiB each and 20 MiB total.", "items": { "properties": { "fileId": { "minLength": 1, "type": "string" }, "projectId": { "type": "string" } }, "required": [ "fileId" ], "type": "object" }, "maxItems": 5, "type": "array" }, "bcc": { "description": "Delivered but never written into the message or the transcript (only a count is recorded).", "items": { "type": "string" }, "type": "array" }, "cc": { "items": { "type": "string" }, "type": "array" }, "clientDedupeKey": { "maxLength": 64, "type": "string" }, "externalChatId": { "minLength": 1, "type": "string" }, "format": { "enum": [ "plain", "markdown" ], "type": "string" }, "omitSignature": { "description": "Skip the channel's signature on this message (v50)", "type": "boolean" }, "replyAll": { "description": "Also send to everyone the newest inbound message was addressed to (its To and Cc)", "minus this mailbox (v50)": null, "type": "boolean" }, "replyInstructions": { "description": "Linked Clanker address only - how its Agent should handle the answer", "maxLength": 2000, "type": "string" }, "sourceSessionId": { "type": "string" }, "startConversation": { "description": "Email only - write to an address that has not written in; externalChatId is the recipient and subject is required", "type": "boolean" }, "subject": { "maxLength": 200, "type": "string" }, "text": { "minLength": 1, "type": "string" }, "to": { "description": "Further To recipients (v50, email only). Up to 20 across to, cc and bcc; duplicates and the mailbox's own address are refused.", "items": { "type": "string" }, "type": "array" } }, "required": [ "externalChatId", "text" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Sent", "with the platform message id and transcript entry": null }, "202": { "description": "The mail server accepted the body but did not confirm delivery; the message is recorded as delivery-uncertain and must not be blindly resent" }, "404": { "description": "Chat not found" }, "409": { "description": "Channel inactive or chat archived" }, "413": { "description": "Reply body is larger than the accepted limit" }, "422": { "description": "An attachment was not found", "has a disallowed type": null, "is too large": null, "or the channel is not email": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Send a human operator reply into one chat, addressed by externalChatId in the body" } }, "/v1/workspace/channels/{channelId}/chats/state": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "open | pending | snoozed | closed. snoozed requires a future snoozeUntil; a new inbound message reopens snoozed and closed conversations.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "externalChatId": { "minLength": 1, "type": "string" }, "snoozeUntil": { "format": "date-time", "type": "string" }, "state": { "enum": [ "open", "pending", "snoozed", "closed" ], "type": "string" } }, "required": [ "externalChatId", "state" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "State updated" }, "400": { "description": "Invalid state or snoozeUntil" }, "404": { "description": "Chat not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Set a conversation's workflow state" } }, "/v1/workspace/channels/{channelId}/drafts": { "get": { "description": "Returns drafts a draft-granted agent proposed instead of sending. Filter by status (e.g. pending) and chatId (one conversation). A draft leaves the building only when a human approves it.", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "pending", "sent", "rejected", "superseded", "failed" ], "type": "string" } }, { "in": "query", "name": "chatId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The channel's drafts" }, "404": { "description": "Channel not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "List draft replies awaiting human approval on a channel" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/channels/{channelId}/drafts/{draftId}": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "draftId", "required": true, "schema": { "pattern": "^chdraft_[a-f0-9]{24}$", "type": "string" } } ], "patch": { "description": "Replaces the draft text. Only a pending draft is editable; a decided draft returns 409.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "attachments": { "description": "Replaces the draft's files when present; an empty list clears them. Workspace files to send (email only). Each is resolved from the caller's own storage, must be an allowed document or image type, at most 10 MiB each and 20 MiB total.", "items": { "properties": { "fileId": { "minLength": 1, "type": "string" }, "projectId": { "type": "string" } }, "required": [ "fileId" ], "type": "object" }, "maxItems": 5, "type": "array" }, "body": { "minLength": 1, "type": "string" }, "format": { "enum": [ "plain", "markdown" ], "type": "string" } }, "required": [ "body" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Draft updated" }, "400": { "description": "Body missing or too long" }, "404": { "description": "Channel or draft not found" }, "409": { "description": "Draft is no longer pending" }, "422": { "description": "An attachment is not sendable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Edit a pending draft's body before approval" } }, "/v1/workspace/channels/{channelId}/drafts/{draftId}/approve": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "draftId", "required": true, "schema": { "pattern": "^chdraft_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Human approval is the only path a draft leaves the building. At-most-once - the draft is claimed for decision and the outbound send is claimed before the platform call, so a double approval never sends twice.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Draft sent (or already delivered)" }, "202": { "description": "Delivery uncertain - the mail server accepted but did not confirm" }, "404": { "description": "Channel or draft not found" }, "409": { "description": "Draft already decided", "or channel inactive": null }, "422": { "description": "The platform service window is closed" }, "502": { "description": "The platform rejected the send" } }, "security": [ { "cookieAuth": [] } ], "summary": "Approve a draft and send it externally" } }, "/v1/workspace/channels/{channelId}/drafts/{draftId}/reject": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "draftId", "required": true, "schema": { "pattern": "^chdraft_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Marks the draft rejected and flips its transcript message so the thread stops offering approve controls. Nothing is sent.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Draft rejected" }, "404": { "description": "Channel or draft not found" }, "409": { "description": "Draft already decided" } }, "security": [ { "cookieAuth": [] } ], "summary": "Reject a pending draft without sending" } }, "/v1/workspace/channels/{channelId}/grants": { "get": { "description": "Returns the (agent, mode) grants governing which agents may send externally on this channel. Absence of a grant means internal_only (fail-closed).", "responses": { "200": { "description": "The channel's agent send grants" }, "404": { "description": "Channel not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "List per-agent external-send grants for a channel" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "put": { "description": "internal_only (default, clears the grant), draft (agent drafts and a human approves before send), or auto (trusted, sends directly). Owner/admin only; agents cannot grant themselves.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "agentId": { "minLength": 1, "type": "string" }, "dailySendCap": { "minimum": 0, "type": "integer" }, "mode": { "enum": [ "internal_only", "draft", "auto" ], "type": "string" } }, "required": [ "agentId", "mode" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Grant updated" }, "404": { "description": "Channel not found" }, "422": { "description": "The WhatsApp service window is closed" }, "429": { "description": "Operator send rate limit reached" }, "502": { "description": "The platform rejected the send" } }, "security": [ { "cookieAuth": [] } ], "summary": "Set an agent's external-send mode on a channel" } }, "/v1/workspace/channels/{channelId}/groups": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "OBA-gated Groups API - invite-only, at most 8 participants. Creation is asynchronous on Meta's side; when the group id cannot be resolved immediately the chat registers itself through the group_lifecycle_update webhook.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "agentId": { "pattern": "^agent_[a-f0-9]{24}$", "type": "string" }, "subject": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": [ "subject" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Group created with its invite link" }, "202": { "description": "Group creation accepted; the chat registers via webhook" }, "400": { "description": "Not a WhatsApp channel or invalid subject" }, "422": { "description": "Meta rejected the group request" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a business WhatsApp group and register it as a chat" } }, "/v1/workspace/channels/{channelId}/operators": { "get": { "description": "Organization owners and admins plus live members of teams linked to the channel. These are the only valid assignment, handoff and mention targets.", "responses": { "200": { "description": "Operators with their display names" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the people who can act on this channel's conversations" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/channels/{channelId}/poll": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Runs one bounded poll (about 20 seconds, up to 25 messages) under the same lease the scheduled poller uses, so the two never overlap. Email channels only; a managed project address receives mail as it arrives and answers 409. Rate limited to 6 checks a minute per channel. The outcome is always a 200 — a mailbox failure is recorded on the channel and returned as `error`.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "backlog": { "description": "More mail is waiting; the next scheduled check runs in about 30 seconds", "type": "boolean" }, "email": { "$ref": "#/components/schemas/WorkspaceEmailSyncState" }, "error": { "type": "string" }, "fetched": { "description": "Messages imported by this check", "type": "integer" }, "ok": { "type": "boolean" }, "skipped": { "description": "The check did not run (another one was already in progress)", "type": "boolean" } }, "type": "object" } } }, "description": "Poll outcome" }, "409": { "description": "Not an active mailbox", "or a check is already running": null }, "429": { "description": "Checked too often" } }, "security": [ { "cookieAuth": [] } ], "summary": "Check a mailbox for new mail now" } }, "/v1/workspace/channels/{channelId}/receipts": { "get": { "parameters": [ { "in": "query", "name": "externalChatId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Only receipts that changed (sent, delivered or read) after this instant (v52), for incremental polling.", "in": "query", "name": "since", "required": false, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "description": "Receipts newest first (sent/delivered/read/failed with timestamps and source)" }, "400": { "description": "Missing externalChatId or invalid limit" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delivery receipts for one conversation's outbound messages" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/channels/{channelId}/teams": { "get": { "responses": { "200": { "description": "Linked teams" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the teams whose members may operate this channel" }, "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "put": { "description": "Every team must be owned by the same workspace principal as the channel. Members of a linked team can read, reply to, note, assign and decide drafts in this channel's conversations, but never administer the channel.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "teamIds": { "items": { "type": "string" }, "maxItems": 50, "type": "array" } }, "required": [ "teamIds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The linked teams after the change" }, "403": { "description": "Only an owner or admin may link teams" }, "422": { "description": "A team is not owned by this workspace" } }, "security": [ { "cookieAuth": [] } ], "summary": "Replace the channel's team links (owner/admin)" } }, "/v1/workspace/channels/{channelId}/test": { "parameters": [ { "in": "path", "name": "channelId", "required": true, "schema": { "pattern": "^channel_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Credential accepted by the platform" }, "422": { "description": "The platform rejected the credential" } }, "security": [ { "cookieAuth": [] } ], "summary": "Re-validate the sealed platform credential" } }, "/v1/workspace/custom-tools": { "get": { "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "List account-owned tool descriptors" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCustomToolDraftRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Save a new editable tool draft" } }, "/v1/workspace/custom-tools/build": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Build or repair a draft with billed inference; never executes or enables it" } }, "/v1/workspace/custom-tools/catalog": { "get": { "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "List composable built-in operations" } }, "/v1/workspace/custom-tools/{toolId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete an unused tool at the expected revision" }, "get": { "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Read the owner draft" }, "parameters": [ { "in": "path", "name": "toolId", "required": true, "schema": { "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCustomToolDraftRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Save a revision-fenced draft or disable a tool" } }, "/v1/workspace/custom-tools/{toolId}/enable": { "parameters": [ { "in": "path", "name": "toolId", "required": true, "schema": { "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Freeze dependencies and enable an immutable version" } }, "/v1/workspace/custom-tools/{toolId}/versions": { "get": { "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "List immutable tool versions; optionally read one exact version" }, "parameters": [ { "in": "path", "name": "toolId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/data-deletion": { "post": { "description": "Preview returns an account-bound, expiring review token and counts. After three warnings, begin requires confirmed=true and the exact lowercase word delete. Begin fences new content and returns active browser IDs for the Workspace edge to close. Delete completes remote cleanup and transactional removal. Failed cleanup stays fenced and can be resumed with the same token. Workspace scope keeps authentication, subscription, credits, billing and quota history. Project/family scopes remove owned content, not global attachments or another user's copies. Storage cleanup is queued durably before success.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "preview", "begin", "delete" ], "type": "string" }, "confirmation": { "enum": [ "delete" ], "type": "string" }, "confirmed": { "type": "boolean" }, "family": { "maxLength": 80, "type": "string" }, "projectId": { "type": "string" }, "scope": { "enum": [ "workspace", "project", "family" ], "type": "string" }, "token": { "pattern": "^[a-f0-9]{48}$", "type": "string" } }, "required": [ "action" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Deletion review, browser cleanup instructions, or completed deletion" }, "400": { "description": "Invalid scope or missing exact confirmation" }, "401": { "description": "Login required" }, "404": { "description": "Target or review is not owned by this account" }, "409": { "description": "Review expired, target changed, or deletion is still running" }, "503": { "description": "Cleanup is unfinished; retry the same deletion" } }, "security": [ { "cookieAuth": [] } ], "summary": "Review and permanently delete owned Workspace content" } }, "/v1/workspace/data-policy": { "get": { "operationId": "workspaceBusinessDataPolicyRead", "responses": { "200": { "description": "Success" }, "403": { "description": "Business owner or administrator required" }, "409": { "description": "Policy revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read owner-scoped Business data controls" }, "patch": { "description": "Default PATCH updates the versioned saved-data policy. With action=requirements, stores countryCode, processingLocation, residencyLocation, gdprRequired and revision as review requirements only; this does not activate a routing or residency boundary.", "operationId": "workspaceBusinessDataPolicyUpdate", "parameters": [ { "in": "query", "name": "action", "schema": { "enum": [ "requirements" ], "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Success" }, "403": { "description": "Business owner or administrator required" }, "409": { "description": "Policy revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update owner-scoped Business data controls or save review requirements" }, "post": { "description": "With action=controls, explicitly enrolls saved-data controls without changing model processing. With action=zdr, the body specifies enable, disable, progress or cancel and the expected revision. Enable requires current terms acceptance and optionally processingLocation from the verified catalog; disable requires confirmDisable. Unavailable selected regions never fall back to another region. The default request accepts the current terms for an enrolled owner.", "operationId": "workspaceBusinessTermsAccept", "parameters": [ { "in": "query", "name": "action", "schema": { "enum": [ "controls", "zdr" ], "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Success" }, "403": { "description": "Business owner or administrator required" }, "409": { "description": "Policy revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Accept terms or explicitly activate Business controls and Gemini ZDR" } }, "/v1/workspace/desktop": { "get": { "responses": { "200": { "description": "Cloud Desktop state and effective commercial-tier policy" }, "503": { "description": "Cloud Desktop is not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read Cloud Desktop entitlement, daily allowance, and lifecycle state" } }, "/v1/workspace/desktop/actions": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Signed runtime dispatch prepared" }, "409": { "description": "Human currently controls the desktop" } }, "security": [ { "cookieAuth": [] } ], "summary": "Prepare one idempotent Secretary computer action" } }, "/v1/workspace/desktop/controller/{action}": { "parameters": [ { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "take", "release" ], "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Controller lease changed" }, "409": { "description": "Desktop controller changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Take human control or return the desktop to Secretary" } }, "/v1/workspace/desktop/start": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "202": { "description": "Cloud Desktop is starting or already active" }, "402": { "description": "Machine or keep-running access is not included in the plan" }, "429": { "description": "Daily Cloud Desktop allowance is exhausted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Start or reconnect the authenticated account's Cloud Desktop" } }, "/v1/workspace/desktop/stop": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "202": { "description": "Cloud Desktop is stopping" } }, "security": [ { "cookieAuth": [] } ], "summary": "Checkpoint and stop the authenticated account's Cloud Desktop" } }, "/v1/workspace/desktop/viewer-ticket": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Viewer ticket issued" }, "409": { "description": "Desktop or controller is unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Issue a short-lived one-use Cloud Desktop viewer ticket" } }, "/v1/workspace/environment": { "get": { "responses": { "200": { "description": "Environment policy and current lifecycle state" }, "503": { "description": "Persistent Workspace is feature-disabled" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read or create the authenticated account's stable Workspace environment" }, "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "preferredMachineType": { "enum": [ "standard-1", "standard-2", "standard-3", "standard-4" ], "type": "string" } }, "required": [ "preferredMachineType", "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Environment policy updated" }, "409": { "description": "Environment revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Select the preferred Standard 1-4 machine for future work" } }, "/v1/workspace/environment/stop": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "202": { "description": "Environment checkpointed and stopped" }, "409": { "description": "Environment is busy or unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Checkpoint and stop the current Workspace machine" } }, "/v1/workspace/external-agent-sessions": { "post": { "description": "Creates a Session, its initial task message and an external executor run without inference. Exchanges only this login for a Session-bound cookie; keep the returned Set-Cookie in the private jar and retain the CSRF cookie/header. Do not reuse a human browser cookie. Identical stable-key retries return the same active Session and cookie without rotation. For a lost initial response, the original disabled private cookie can retry only this exact transition within five minutes while the task and replacement cookie remain active, with matching CSRF and organization. It cannot access other APIs. Conflicting inputs, another login, finished/deleted tasks and taken-over Sessions cannot restart the task. The provider/name are informational client labels, not verified provider identity. Normal account/organization permissions remain enforced.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgentSessionStart" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgentSessionResponse" } } }, "description": "Identical active task returned with the same private cookie, including bounded lost-response recovery" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgentSessionResponse" } } }, "description": "Session and run created; use the new private cookie and returned run ID/executor ID", "headers": { "Set-Cookie": { "description": "Session-bound HttpOnly cookie; retain privately", "schema": { "type": "string" } } } }, "409": { "description": "Conflicting input", "inactive task": null, "or takeover; never restart automatically": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Begin a visible external-agent Session from a dedicated private cookie login" } }, "/v1/workspace/external-agent-sessions/{sessionId}/takeover": { "parameters": [ { "in": "path", "name": "sessionId", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Revokes the dedicated agent cookie, fences transcript/file publication, cancels the task and requests cancellation of linked cloud work. Preserves history/files and makes the same Session available for normal Workspace conversation. Opening/reading never takes over. The agent cookie itself cannot perform this action. Repeated takeover is safe. Previously submitted outside effects cannot be recalled.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAgentSessionResponse" } } }, "description": "Workspace controls this Session" }, "403": { "description": "Independent Workspace login or current organization build role required" }, "404": { "description": "Session unavailable to this account" }, "502": { "description": "Agent access revoked but a runtime stop could not be confirmed; reread Session and inspect Jobs" } }, "security": [ { "cookieAuth": [] } ], "summary": "Take over an external-agent Session using the user's independent Workspace login" } }, "/v1/workspace/file-requests": { "get": { "operationId": "clientFileRequest0Get", "responses": { "200": { "description": "Request result" }, "201": { "description": "Created" }, "403": { "description": "Access denied" }, "404": { "description": "Unavailable" }, "409": { "description": "Already used or invalid submission" }, "410": { "description": "Expired or revoked" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage owner file requests" }, "post": { "operationId": "clientFileRequest0Post", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Request result" }, "201": { "description": "Created" }, "403": { "description": "Access denied" }, "404": { "description": "Unavailable" }, "409": { "description": "Already used or invalid submission" }, "410": { "description": "Expired or revoked" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage owner file requests" } }, "/v1/workspace/file-requests/collections": { "post": { "operationId": "clientFileRequest1Post", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Request result" }, "201": { "description": "Created" }, "403": { "description": "Access denied" }, "404": { "description": "Unavailable" }, "409": { "description": "Already used or invalid submission" }, "410": { "description": "Expired or revoked" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage owner file requests" } }, "/v1/workspace/file-requests/collections/{collectionId}": { "patch": { "operationId": "clientFileRequest2Patch", "parameters": [ { "in": "path", "name": "collectionId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Request result" }, "201": { "description": "Created" }, "403": { "description": "Access denied" }, "404": { "description": "Unavailable" }, "409": { "description": "Already used or invalid submission" }, "410": { "description": "Expired or revoked" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage owner file requests" } }, "/v1/workspace/file-requests/{requestId}": { "delete": { "operationId": "clientFileRequest3Delete", "parameters": [ { "in": "path", "name": "requestId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Request result" }, "201": { "description": "Created" }, "403": { "description": "Access denied" }, "404": { "description": "Unavailable" }, "409": { "description": "Already used or invalid submission" }, "410": { "description": "Expired or revoked" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage owner file requests" } }, "/v1/workspace/image-generations": { "post": { "description": "Requires a signed Workspace request and live Session run. Scope and Agent permissions are checked by the server. requestKey is the stable tool call ID. Returns the same receipt for an identical repeated request. Reference images must be exact current-project PNG or JPEG file revisions. Standard accounts only; disabled by default.", "operationId": "workspaceImageCreate", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "aspectRatio": { "default": "1:1", "type": "string" }, "maxCredits": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" }, "outputPath": { "description": "New relative PNG path. Existing files are never replaced.", "type": "string" }, "projectId": { "type": "string" }, "prompt": { "maxLength": 8000, "type": "string" }, "referenceImages": { "items": { "properties": { "fileId": { "type": "string" }, "revision": { "minimum": 1, "type": "integer" } }, "required": [ "fileId", "revision" ], "type": "object" }, "maxItems": 3, "type": "array" }, "requestKey": { "maxLength": 200, "type": "string" }, "runId": { "type": "string" }, "sessionId": { "type": "string" }, "size": { "default": "1K", "enum": [ "1K" ], "type": "string" } }, "required": [ "projectId", "sessionId", "runId", "requestKey", "prompt", "outputPath" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Current receipt or idempotent submission" }, "202": { "description": "Queued durable image job; not saved delivery" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "402": { "description": "Estimate exceeds credit cap" }, "403": { "description": "Disabled feature, inference boundary or missing editor or Agent permission" }, "404": { "description": "Job unavailable in this project" }, "409": { "description": "Path, reference revision or idempotency conflict" }, "413": { "description": "Project storage quota exceeded" }, "429": { "description": "Account image concurrency limit reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Generate an image in the active Session project" } }, "/v1/workspace/image-generations/{id}": { "get": { "operationId": "workspaceImageGet", "parameters": [ { "in": "query", "name": "projectId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current receipt or idempotent submission" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Disabled feature, inference boundary or missing editor or Agent permission" }, "404": { "description": "Job unavailable in this project" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read an existing project image job" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/image-generations/{id}/cancel": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceImageCancel", "parameters": [ { "in": "query", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Current receipt or idempotent submission" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "403": { "description": "Disabled feature, inference boundary or missing editor or Agent permission" }, "404": { "description": "Job unavailable in this project" } }, "security": [ { "cookieAuth": [] } ], "summary": "Cancel a project image job" } }, "/v1/workspace/jobs": { "get": { "responses": { "200": { "description": "Recent jobs" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the authenticated account's recent durable Workspace jobs" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "anyOf": [ { "required": [ "command" ] }, { "required": [ "script" ] } ], "properties": { "command": { "maxLength": 32768, "type": "string" }, "expectedOutputs": { "items": { "properties": { "equals": { "description": "Exact top-level scalar field values for JSON or YAML. Values must be string (at most 1024 bytes), finite number (absolute value at most 9007199254740991), boolean, or null. Expected values must not contain Secrets.", "maxProperties": 32, "type": "object" }, "format": { "default": "file", "enum": [ "file", "json", "jsonl", "yaml", "csv" ], "type": "string" }, "maxRows": { "maximum": 100000000, "minimum": 0, "type": "integer" }, "minBytes": { "format": "int64", "maximum": 53687091200, "minimum": 0, "type": "integer" }, "minRows": { "maximum": 100000000, "minimum": 0, "type": "integer" }, "path": { "maxLength": 512, "type": "string" }, "requiredKeys": { "description": "Required top-level object keys or CSV header names; array and JSONL checks apply to every record.", "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 32, "type": "array", "uniqueItems": true } }, "required": [ "path" ], "type": "object" }, "maxItems": 32, "type": "array" }, "idempotencyKey": { "maxLength": 200, "minLength": 12, "type": "string" }, "kind": { "default": "exec", "enum": [ "exec" ], "type": "string" }, "projectId": { "type": "string" }, "script": { "additionalProperties": false, "description": "A saved script invocation. The server derives the command and Python scripts receive mandatory preflight checks. Cannot be combined with an environment change.", "properties": { "arguments": { "items": { "maxLength": 32768, "type": "string" }, "maxItems": 64, "type": "array" }, "interpreter": { "maxLength": 200, "type": "string" }, "interpreterArgs": { "items": { "maxLength": 32768, "type": "string" }, "maxItems": 64, "type": "array" }, "path": { "maxLength": 512, "type": "string" } }, "required": [ "path" ], "type": "object" }, "sessionId": { "type": "string" }, "timeoutSeconds": { "default": 600, "maximum": 3600, "minimum": 1, "type": "integer" }, "workspaceRunId": { "type": "string" } }, "required": [ "idempotencyKey" ], "type": "object" } } }, "required": true }, "responses": { "202": { "description": "Job durably queued" }, "402": { "description": "Insufficient compute credits" } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue one command in the authenticated account's persistent Workspace environment" } }, "/v1/workspace/jobs/{jobId}": { "get": { "responses": { "200": { "description": "Job state and result" }, "404": { "description": "Job not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one account-owned durable Workspace job" }, "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "pattern": "^workspace_job_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/jobs/{jobId}/cancel": { "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "pattern": "^workspace_job_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "202": { "description": "Cancellation accepted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Cancel one queued or running account-owned Workspace job" } }, "/v1/workspace/jobs/{jobId}/events": { "get": { "parameters": [ { "in": "query", "name": "after", "required": false, "schema": { "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "description": "Job event page" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read an incremental event page for one account-owned Workspace job" }, "parameters": [ { "in": "path", "name": "jobId", "required": true, "schema": { "pattern": "^workspace_job_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/lab": { "get": { "operationId": "workspaceLabConfigurationGet", "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabConfiguration" } }, "/v1/workspace/lab/operations/{operationId}": { "get": { "operationId": "workspaceLabOperationGet", "parameters": [ { "description": "Return read-only terminal or exact deployment readiness evidence. This GET does not block or cancel work.", "in": "query", "name": "waitFor", "required": false, "schema": { "enum": [ "terminal", "ready" ], "type": "string" } } ], "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabOperation" }, "parameters": [ { "in": "path", "name": "operationId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/lab/resources": { "get": { "operationId": "workspaceLabResourcesGet", "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResources" }, "post": { "operationId": "workspaceLabResourcesPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResources" } }, "/v1/workspace/lab/resources/{resourceId}": { "get": { "operationId": "workspaceLabResourceGet", "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResource" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/lab/resources/{resourceId}/failed-deployments": { "get": { "operationId": "workspaceLabFailedDeploymentsGet", "responses": { "200": { "description": "Failed deployment eligibility or saved cleanup receipt" }, "202": { "description": "Cleanup continuation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabFailedDeployments" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceLabFailedDeploymentsPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Failed deployment eligibility or saved cleanup receipt" }, "202": { "description": "Cleanup continuation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabFailedDeployments" } }, "/v1/workspace/lab/resources/{resourceId}/grants": { "delete": { "operationId": "workspaceLabResourceGrantsDelete", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResourceGrants" }, "get": { "operationId": "workspaceLabResourceGrantsGet", "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResourceGrants" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/lab/resources/{resourceId}/inference": { "get": { "operationId": "workspaceLabResourceInferenceGet", "responses": { "200": { "description": "Bounded AI request audit metadata without prompts or completions" }, "403": { "description": "Logs permission required" }, "404": { "description": "Resource not found or not visible" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read Workspace Lab AI request history" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/lab/resources/{resourceId}/memory": { "delete": { "operationId": "workspaceLabResourceMemoryDelete", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expectedRevision": { "format": "int64", "type": "integer" }, "markdown": { "type": "string" } }, "required": [ "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Current memory document and revision" }, "403": { "description": "Deploy permission required" }, "409": { "description": "Memory changed since the supplied revision" } }, "security": [ { "cookieAuth": [] } ], "summary": "Clear app deployment memory" }, "get": { "operationId": "workspaceLabResourceMemoryGet", "responses": { "200": { "description": "Current memory document and revision" }, "403": { "description": "Deploy permission required" }, "409": { "description": "Memory changed since the supplied revision" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read persistent app deployment memory" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/lab/resources/{resourceId}/operations": { "get": { "operationId": "workspaceLabResourceOperationsGet", "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResourceOperations" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceLabResourceOperationsPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResourceOperations" } }, "/v1/workspace/lab/resources/{resourceId}/preparation": { "get": { "operationId": "workspaceLabResourcePreparationGet", "responses": { "200": { "description": "Current preparation", "visible service draft identities and recent authorized launch plans": null }, "403": { "description": "Source access denied" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read app preparation and assessed service drafts" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Supports existing preparation actions and create_service with an exact serviceId, sourceId and preparation expectedRevision. An optional projectId confines the request and requestKey binds retries to the same input. Service creation preserves independent code and fresh consent without executing it. Assessed database/storage dependencies create empty private managed data drafts without copying source, importing data or provisioning. approve_services accepts the exact assessment/source, serviceIds, per-service maximumMicrounits and per-build buildMaximumMicrounits ceilings and a stable requestKey. Optional userDataMode (private or shared) records the owner-approved personal-data adaptation requirement; private requires verified server identities and two-user isolation tests. Optional connections select a serviceId, assessed dependencyId, exact targetResourceId/targetRevision, alias and read/write access in the same writable project. Current management and data/run grants are required. It atomically saves those connections and queues untouched copied services, preserves original code, and does not provision or deploy. Repeating an accepted key recovers its receipt without restarting sessions. launch_services accepts projectId, a stable requestKey and 1-32 steps (id, resourceId, expectedRevision, action build/deploy/provision/ready, maximumMicrounits, needs). It saves explicit startup ordering and per-operation budgets; ready captures an existing exact readiness receipt without starting compute. Cycles, missing connection barriers and stale resources are rejected. The scheduler rechecks authority, submits at most three independent operations per plan per tick, recovers stable admission keys and waits for exact readiness. stop_launch with launchId stops unsubmitted steps without canceling accepted operations. GET includes the ten most recent authorized launches and their saved progress.", "operationId": "workspaceLabResourcePreparationPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Preparation", "source change or service draft receipt": null }, "403": { "description": "Source or project authority denied" }, "409": { "conflicting request or unavailable source/draft": null, "description": "Stale assessment" } }, "security": [ { "cookieAuth": [] } ], "summary": "Continue app preparation or create an assessed service draft" } }, "/v1/workspace/lab/resources/{resourceId}/sources": { "get": { "operationId": "workspaceLabResourceSourcesGet", "responses": { "200": { "description": "Source metadata and ready or pending storage state" }, "403": { "description": "Source access denied" } }, "security": [ { "cookieAuth": [] } ], "summary": "List saved Lab source versions" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Upload uses archiveBase64 or a public HTTPS ZIP URL and an analysis limit. Reuse copies a complete verified archive to an independent object, requires source access and writable project links on both apps, and creates stopped unapproved preparation without model or compute work. Reuse never replaces existing target source; requestKey recovers the same saved receipt.", "operationId": "workspaceLabResourceSourcesPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "archiveBase64", "maximumMicrounits" ] }, { "required": [ "url", "maximumMicrounits" ] }, { "required": [ "action", "sourceResourceId", "sourceId", "requestKey" ] } ], "properties": { "action": { "enum": [ "reuse" ], "type": "string" }, "archiveBase64": { "type": "string" }, "expectedRevision": { "format": "int64", "minimum": 1, "type": "integer" }, "maximumMicrounits": { "format": "int64", "minimum": 1, "type": "integer" }, "projectId": { "type": "string" }, "requestKey": { "maxLength": 160, "minLength": 16, "type": "string" }, "sourceId": { "type": "string" }, "sourceResourceId": { "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": [ "projectId", "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Existing source or durable reuse receipt" }, "201": { "description": "Uploaded source and saved resource" }, "400": { "description": "Invalid archive or source selection" }, "403": { "description": "Source access denied" }, "409": { "description": "Revision", "scope": null, "target state or receipt conflict": null }, "413": { "description": "Workspace source storage quota exceeded" }, "503": { "description": "Source storage unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Upload source or reuse an exact version in an empty draft" } }, "/v1/workspace/lab/resources/{resourceId}/ticket": { "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceLabResourceTicketPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResourceTicket" } }, "/v1/workspace/lab/resources/{resourceId}/versions": { "get": { "operationId": "workspaceLabResourceVersionsGet", "responses": { "200": { "description": "Resource or durable receipt" }, "202": { "description": "Operation queued" }, "403": { "description": "Permission denied" }, "409": { "description": "Stale revision or conflicting request key" }, "503": { "description": "Lab execution not configured" } }, "security": [ { "cookieAuth": [] } ], "summary": "Workspace LabResourceVersions" }, "parameters": [ { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/marketplace-installations": { "post": { "description": "With workspaceMarketplaceReconciliation support, existingAgentId and expectedAgentRevision explicitly select an owned older import, even when several copies exist. The exact license and version must match. Connecting preserves every copy's edits, enabled state, jobs, learning and release selection. A missing selected Agent never creates a replacement, and an already connected different copy returns a conflict. Recover uncertain responses with the original requestKey and full request; a committed receipt returns current owner-edited Agent data after later changes.", "operationId": "workspaceMarketplaceInstall", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "existingAgentId": { "description": "Optional exact existing import to connect; requires expectedAgentRevision", "type": "string" }, "expectedAgentRevision": { "description": "Required with existingAgentId", "minimum": 1, "type": "integer" }, "expectedDigest": { "maxLength": 64, "minLength": 64, "type": "string" }, "expectedPackageSchemaVersion": { "description": "Required for an executable package. Older servers reject this field instead of ignoring the workflow.", "enum": [ "clanker.marketplace.package.v1", "clanker.marketplace.package.v2", "clanker.marketplace.managed-package.v1" ], "type": "string" }, "expectedVersionId": { "type": "string" }, "licenseId": { "type": "string" }, "modelId": { "type": "string" }, "requestKey": { "type": "string" } }, "required": [ "requestKey", "licenseId", "expectedVersionId", "expectedDigest" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Installed Agent and durable installation receipt" }, "400": { "description": "Invalid installation request" }, "404": { "description": "License or selected existing import not found" }, "409": { "changed Agent revision or conflicting installation": null, "description": "Package unavailable" }, "410": { "description": "Previously installed Agent was deleted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Install an exact licensed Agent or connect a selected older import" } }, "/v1/workspace/media": { "get": { "operationId": "workspaceMediaList", "parameters": [ { "in": "query", "name": "projectId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "fileId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "List authorized video analyses" }, "post": { "operationId": "workspaceMediaCreate", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "202": { "description": "Success" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" }, "413": { "description": "Video or storage limit exceeded" }, "429": { "description": "Analysis concurrency limit reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue analysis of an immutable workspace video revision" } }, "/v1/workspace/media/{id}": { "get": { "operationId": "workspaceMediaGet", "responses": { "200": { "description": "Success" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read authorized video analysis and separate evidence coverage" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/media/{id}/cancel": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceMediaCancel", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Cancel a video analysis" } }, "/v1/workspace/media/{id}/export": { "get": { "operationId": "workspaceMediaExport", "parameters": [ { "in": "query", "name": "format", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Export authorized video analysis results" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/media/{id}/preview": { "get": { "operationId": "workspaceMediaPreview", "parameters": [ { "in": "query", "name": "kind", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "206": { "description": "Partial video stream" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" }, "416": { "description": "Requested range unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Stream an authorized video source or thumbnail" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/ontology/experiences": { "get": { "description": "purpose=manage includes every owned lesson. purpose=recall requires one project and status=approved, enforces the current memory switch and selected-Agent applicability, and accepts the actual owned agentId or no Agent. Legacy requests omit restricted lessons.", "operationId": "workspaceExperiencesGet", "parameters": [ { "in": "query", "name": "purpose", "schema": { "enum": [ "manage", "recall" ], "type": "string" } }, { "in": "query", "name": "agentId", "schema": { "type": "string" } }, { "in": "query", "name": "projectId", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string" } }, { "in": "query", "name": "kind", "schema": { "type": "string" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" }, "post": { "description": "Optional applicability contains mode=project with empty agentIds, or mode=agents with 1 to 100 distinct owned Agent IDs compatible with the lesson project. New records default to project applicability; omitted applicability on edits preserves the saved scope. Scope edits advance the Experience revision and preserve source evidence. Existing releases and separately attached Skills remain unchanged.", "operationId": "workspaceExperiencesPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Experience response" }, "201": { "description": "Experience created" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" } }, "/v1/workspace/ontology/experiences/retry-learning": { "post": { "operationId": "workspaceExperienceRetryLearningPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" } }, "/v1/workspace/ontology/experiences/settings": { "get": { "operationId": "workspaceExperienceSettingsGet", "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" }, "patch": { "operationId": "workspaceExperienceSettingsPatch", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" } }, "/v1/workspace/ontology/experiences/{id}": { "delete": { "operationId": "workspaceExperienceDelete", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "revision", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" }, "get": { "operationId": "workspaceExperienceGet", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" }, "patch": { "description": "Optional applicability contains mode=project with empty agentIds, or mode=agents with 1 to 100 distinct owned Agent IDs compatible with the lesson project. New records default to project applicability; omitted applicability on edits preserves the saved scope. Scope edits advance the Experience revision and preserve source evidence. Existing releases and separately attached Skills remain unchanged.", "operationId": "workspaceExperiencePatch", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" } }, "/v1/workspace/ontology/experiences/{id}/skill": { "post": { "description": "Creates or updates the linked Skill using expectedRevision and expectedSkillRevision. Optional createSeparateSkill=true creates a new Skill identity from the saved procedure and updates only the Experience link, preserving the previous Skill and all consumer attachments. The original Skill must still match its expected revision. All writes commit together.", "operationId": "workspaceExperienceSkillPost", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Experience response" }, "400": { "description": "Invalid request" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" }, "409": { "description": "Revision conflict" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage account-owned Workspace experience and learning" } }, "/v1/workspace/ontology/learning-lineage": { "get": { "description": "Read-only version 1 neighborhood of owned records. Returns a root, at most 40 connections and their nodes, plus a root-scoped cursor. Each page is one consistent snapshot. Deleted or inaccessible sources are excluded. Connections do not certify task quality. No private instructions, lesson bodies or test/provider contents are returned.", "operationId": "workspaceLearningLineageRead", "parameters": [ { "description": "Opt in to file_check nodes and checks_job_file links", "in": "query", "name": "includeFileChecks", "schema": { "default": false, "type": "boolean" } }, { "description": "Opt in to hosted iteration and assessment nodes", "in": "query", "name": "includeHostedAssessments", "schema": { "default": false, "type": "boolean" } }, { "description": "Opt in to job_outcome nodes and assesses_job links. Older clients omit these connections.", "in": "query", "name": "includeJobAssessments", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "agent, release, skill_version, run, job, outcome, job_outcome, file_check, experience, candidate, evaluation or promotion", "in": "query", "name": "kind", "required": true, "schema": { "type": "string" } }, { "description": "Original source identifier; promotion uses candidate ID, outcome uses Run ID and job_outcome uses Job ID", "in": "query", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional exact Experience, assessment or Skill revision; omitted selects the currently available revision", "in": "query", "name": "revision", "required": false, "schema": { "type": "string" } }, { "description": "Opaque cursor returned for this same source; refresh after a source revision changes", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Versioned lineage with original root, nodes, directional links and optional nextCursor" }, "400": { "description": "Invalid source or cursor" }, "401": { "description": "Login required" }, "404": { "description": "Source was removed or is unavailable to the owner" }, "409": { "description": "Source changed since the cursor was issued" }, "500": { "description": "Learning history could not be verified" } }, "security": [ { "cookieAuth": [] } ], "summary": "Explore the original sources and versions behind Agent learning" } }, "/v1/workspace/ontology/objects/{id}": { "delete": { "description": "Tombstones the object source and stable record ID, removes its relationships, claims, evidence, and object history, and deletes the backing Wiki resource when applicable.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Ontology object deleted" }, "400": { "description": "Invalid ontology object ID" }, "401": { "description": "Login required" }, "404": { "description": "Ontology object not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Permanently delete one account-owned ontology object" }, "get": { "responses": { "200": { "description": "Object, links, claims, evidence, and timeline" }, "401": { "description": "Login required" }, "404": { "description": "Ontology object not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one account-owned ontology page" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^object_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/ontology/records/{kind}/{id}": { "delete": { "description": "Deletes an individual relationship, claim, evidence record, or Activity event and tombstones its stable ID so deterministic projection cannot recreate it.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Ontology record deleted" }, "400": { "description": "Invalid ontology record" }, "401": { "description": "Login required" }, "404": { "description": "Ontology record not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Permanently delete one account-owned ontology record" }, "parameters": [ { "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "links", "claims", "evidence", "events" ], "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/ontology/{resource}": { "get": { "description": "Reads the independent hosted ontology schema, project summary, objects, timeline, or resolved entity unions. Optional projectId filters remain bound to the authenticated account.", "responses": { "200": { "description": "Workspace ontology response" }, "400": { "description": "Invalid project or query parameters" }, "401": { "description": "Login required" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read the account-scoped Workspace ontology" }, "parameters": [ { "in": "path", "name": "resource", "required": true, "schema": { "enum": [ "schema", "overview", "summary", "objects", "timeline", "unions", "query", "search" ], "type": "string" } } ], "post": { "description": "The query resource searches canonical hosted objects. The search resource also searches Activity, claims, and evidence. Untrusted owner text remains account-bound, and a project search includes General knowledge but never another account.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "limit": { "maximum": 100, "minimum": 1, "type": "integer" }, "projectId": { "type": "string" }, "query": { "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "query" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Matching ontology objects" }, "400": { "description": "Invalid ontology query" }, "401": { "description": "Login required" } }, "security": [ { "cookieAuth": [] } ], "summary": "Search the account-scoped Workspace ontology" } }, "/v1/workspace/organizations": { "get": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Get organization workspace state" }, "post": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Post organization workspace state" } }, "/v1/workspace/organizations/{organizationId}": { "get": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Get organization workspace state" }, "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Patch organization workspace state" } }, "/v1/workspace/organizations/{organizationId}/{collection}": { "delete": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete organization workspace state" }, "get": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Get organization workspace state" }, "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Post organization workspace state" }, "put": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Put organization workspace state" } }, "/v1/workspace/organizations/{organizationId}/{collection}/{resourceId}": { "delete": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete organization workspace state" }, "get": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Get organization workspace state" }, "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Patch organization workspace state" }, "post": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Post organization workspace state" }, "put": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update an organization budget or resource grant" } }, "/v1/workspace/organizations/{organizationId}/{collection}/{resourceId}/{action}": { "delete": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete organization workspace state" }, "parameters": [ { "in": "path", "name": "organizationId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "resourceId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Authenticates the acting person; checks current organization role and resource grants. Mutations retain organization ownership and audit actor.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Organization operation result" } }, "security": [ { "cookieAuth": [] } ], "summary": "Post organization workspace state" } }, "/v1/workspace/preferences": { "get": { "description": "Returns account-scoped Workspace preferences, including the customizable base-agent identity. Missing rows default to My Agent at @agent; clients and runtimes continue accepting the legacy @secretary alias from legacyMentions.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePreferencesResponse" } } }, "description": "Workspace preferences" }, "401": { "description": "Login required" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read account-scoped Workspace preferences" }, "patch": { "description": "Optimistically updates Workspace preferences. Base-agent identity is display-only/prompt identity data and cannot add tools, capabilities, credentials, or secret access.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "baseAgent": { "additionalProperties": false, "properties": { "avatar": { "additionalProperties": false, "properties": { "assetId": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "columns": { "enum": [ 4 ], "type": "integer" }, "generated": { "type": "boolean" }, "height": { "maximum": 2048, "minimum": 512, "type": "integer" }, "layout": { "enum": [ "clanker.agent-avatar.v1" ], "type": "string" }, "mimeType": { "enum": [ "image/png", "image/jpeg" ], "type": "string" }, "rows": { "enum": [ 4 ], "type": "integer" }, "sha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "width": { "maximum": 2048, "minimum": 512, "type": "integer" } }, "required": [ "assetId", "mimeType", "sha256", "width", "height", "columns", "rows", "layout", "generated" ], "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "displayName": { "default": "My Agent", "maxLength": 120, "minLength": 1, "type": "string" }, "instructions": { "maxLength": 24000, "type": "string" }, "mention": { "default": "agent", "pattern": "^@?[A-Za-z0-9](?:[A-Za-z0-9-]{0,46}[A-Za-z0-9])?$", "type": "string" }, "voiceSpeaker": { "enum": [ "angus", "asteria", "arcas", "orion", "orpheus", "athena", "luna", "zeus", "perseus", "helios", "hera", "stella", "google-lite:kore", "google-lite:puck", "google-lite:charon", "google-lite:fenrir", "google-lite:aoede", "google-lite:leda", "google-lite:orus", "google-lite:zephyr", "google:kore", "google:puck", "google:charon", "google:fenrir", "google:aoede", "google:leda", "google:orus", "google:zephyr" ], "type": "string" } }, "required": [ "displayName", "mention", "description", "instructions" ], "type": "object" }, "expectedRevision": { "minimum": 0, "type": "integer" }, "generalProject": { "additionalProperties": false, "properties": { "data": { "type": "object" }, "description": { "maxLength": 4000, "type": "string" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name", "description", "data" ], "type": "object" }, "ontologyContextEnabled": { "default": false, "type": "boolean" } }, "required": [ "ontologyContextEnabled", "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePreferencesResponse" } } }, "description": "Updated Workspace preferences" }, "400": { "description": "Invalid preferences" }, "401": { "description": "Login required" }, "409": { "description": "Preference revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update account-scoped Workspace preferences" } }, "/v1/workspace/projects/{id}/files": { "delete": { "parameters": [ { "in": "query", "name": "path", "required": true, "schema": { "maxLength": 512, "type": "string" } }, { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceProjectFilesResponse" } } }, "description": "Project file deleted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "File revision changed; refresh before retrying" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete one file from an account-owned Workspace project" }, "get": { "description": "Use general for the account's unassigned General workspace. Omitting path lists file metadata. Supplying path returns the exact raw file body. File paths are relative, cannot traverse, and are scoped to the authenticated account and project.", "parameters": [ { "in": "query", "name": "path", "required": false, "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceProjectFilesResponse" } }, "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "description": "Project file list or raw file content", "headers": { "X-Clanker-File-Revision": { "description": "Present for raw file reads.", "schema": { "format": "int64", "minimum": 1, "type": "integer" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Project or file not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "List or read files in an account-owned Workspace project" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } } ], "put": { "description": "Sends the raw file body. expectedRevision must be zero for a new path and the current positive revision when replacing a file. Files are limited to 8 MB.", "parameters": [ { "in": "query", "name": "path", "required": true, "schema": { "maxLength": 512, "type": "string" } }, { "in": "query", "name": "expectedRevision", "required": true, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Optional original browser file media type. The transport body remains application/octet-stream.", "in": "header", "name": "X-Clanker-File-Content-Type", "required": false, "schema": { "maxLength": 120, "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "format": "binary", "type": "string" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceProjectFilesResponse" } } }, "description": "Existing file replaced" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceProjectFilesResponse" } } }, "description": "New file created" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "File revision changed or project storage limit reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create or replace one file in an account-owned Workspace project" } }, "/v1/workspace/projects/{id}/files-v2": { "get": { "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "prefix", "schema": { "type": "string" } }, { "description": "Return only the active file at this exact project path", "in": "query", "name": "path", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 500, "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFilesV2Response" } } }, "description": "File page; follow nextCursor until absent" } }, "security": [ { "cookieAuth": [] } ], "summary": "List paginated object-backed files without loading their bodies into PostgreSQL" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } } ], "patch": { "description": "Each UTF-8 file is limited to 64 KiB. Each oldText must match exactly once in the observed original revision. At most 16 files and 32 edits per file. A conflict saves no partial patch; reread all sources before retrying.", "operationId": "workspaceProjectFilesV2Patch", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFilesV2PatchRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFilesV2Response" } } }, "description": "All file revisions saved" }, "409": { "description": "Revision conflict or unverified completion; read files before retrying" } }, "security": [ { "cookieAuth": [] } ], "summary": "Atomically apply exact text edits to observed file revisions" } }, "/v1/workspace/projects/{id}/files-v2/import-legacy": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Import batch result" }, "413": { "description": "Persistent storage quota exceeded" } }, "security": [ { "cookieAuth": [] } ], "summary": "Import a bounded batch of legacy PostgreSQL-backed Workspace files into object storage" } }, "/v1/workspace/projects/{id}/files-v2/uploads": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUploadCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFilesV2Response" } } }, "description": "Keep upload.id and its private scoped grant to upload parts or resume" }, "409": { "description": "Destination revision changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a direct multipart upload with a scoped expiring grant" } }, "/v1/workspace/projects/{id}/files-v2/uploads/{uploadId}": { "get": { "operationId": "workspaceProjectUploadV2Resume", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFilesV2Response" } } }, "description": "Private upload grant, status and saved ordered part receipts" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Resume an owned unexpired multipart upload" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "uploadId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/projects/{id}/files-v2/uploads/{uploadId}/abort": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } }, { "in": "path", "name": "uploadId", "required": true, "schema": { "pattern": "^workspace_upload_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Upload aborted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Abort a multipart object upload" } }, "/v1/workspace/projects/{id}/files-v2/uploads/{uploadId}/complete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "uploadId", "required": true, "schema": { "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUploadCompleteRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFilesV2Response" } } }, "description": "Immutable revision published; reread the returned file revision to verify content" }, "409": { "description": "Upload or file conflict; inspect destination before retrying" } }, "security": [ { "cookieAuth": [] } ], "summary": "Complete a multipart object upload and publish an immutable revision" } }, "/v1/workspace/projects/{id}/files-v2/uploads/{uploadId}/parts": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "uploadId", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "workspaceProjectUploadV2Parts", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUploadPart" } } }, "required": true }, "responses": { "200": { "description": "Success" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Record uploaded part receipts for safe resumption" } }, "/v1/workspace/projects/{id}/files-v2/{fileId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "File deleted" }, "409": { "description": "File changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Tombstone an object-backed file and its active search blocks" }, "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFilesV2Response" } } }, "description": "File metadata" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read object-backed file metadata" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileV2RenameRequest" } } }, "required": true }, "responses": { "200": { "description": "File renamed" }, "409": { "description": "File changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Rename an object-backed file with optimistic concurrency" } }, "/v1/workspace/projects/{id}/files-v2/{fileId}/content": { "get": { "parameters": [ { "in": "query", "name": "revision", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "307": { "description": "Signed same-origin storage redirect" } }, "security": [ { "cookieAuth": [] } ], "summary": "Redirect to a short-lived signed object download" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/projects/{id}/files-v2/{fileId}/reindex": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "schema": { "pattern": "^workspace_file_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "202": { "description": "Reindex queued" } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue a new ingestion pass for the current immutable file revision" } }, "/v1/workspace/projects/{id}/files-v2/{fileId}/shares": { "get": { "parameters": [ { "description": "Opaque signed continuation cursor scoped to this account and file", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileSharesResponse" } } }, "description": "Active-first owner share page ordered by immutable creation key; use nextCursor until absent" }, "400": { "description": "Invalid or cross-scope cursor" } }, "security": [ { "cookieAuth": [] } ], "summary": "List owner-managed private shares for one exact file" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "schema": { "pattern": "^workspace_file_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Creates read/download-only access after verifying expectedFileRevision. Link sharing is the default product flow and returns a 256-bit shareToken exactly once so the browser can place it in a URL fragment; the service stores only its SHA-256 hash. User recipients must use an already-public @handle because private email/account discovery is not supported. The verified revision is pinned unless followLatest is explicitly true. An account may retain at most 500 active outgoing file shares. This never confers project, job, command, agent, skill, or secret authority.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedFileRevision": { "description": "Exact current file revision reviewed by the owner; stale values return 409", "format": "int64", "minimum": 1, "type": "integer" }, "followLatest": { "default": false, "type": "boolean" }, "recipient": { "description": "Omit or leave empty for link shares; public @handle for user shares or exact team ID for team shares", "maxLength": 254, "type": "string" }, "recipientType": { "description": "Use link for an account-gated bearer link; user and team remain available for named ACL compatibility", "enum": [ "link", "user", "team" ], "type": "string" } }, "required": [ "recipientType", "expectedFileRevision" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileSharesResponse" } } }, "description": "Private file share created; link shares include a one-time shareToken that must be kept in the client-generated URL fragment and sent only in the redeem request body" }, "404": { "description": "Recipient is unavailable" }, "409": { "description": "File or recipient state changed", "duplicate active recipient": null, "or active-share quota reached": null }, "429": { "description": "File share creation rate limited" } }, "security": [ { "cookieAuth": [] } ], "summary": "Share one CAS-verified Workspace file revision by account-gated link, public Clanker handle, or team" } }, "/v1/workspace/projects/{id}/files-v2/{fileId}/shares/{shareId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileSharesResponse" } } }, "description": "Share revoked" }, "409": { "description": "Share ACL changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Revoke an owner-managed private file share at an exact ACL revision" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(general|project_[a-f0-9]{24})$", "type": "string" } }, { "in": "path", "name": "fileId", "required": true, "schema": { "pattern": "^workspace_file_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "shareId", "required": true, "schema": { "pattern": "^workspace_share_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ] }, "/v1/workspace/projects/{id}/index-status": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Index status summary" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read per-project ingestion and searchable-block counts" } }, "/v1/workspace/projects/{id}/search": { "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Citation-preserving search results" } }, "security": [ { "cookieAuth": [] } ], "summary": "Search the authorized project with reciprocal-rank fused lexical and semantic retrieval" } }, "/v1/workspace/projects/{id}/teams": { "get": { "responses": { "200": { "description": "Assigned Team list" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the authenticated account's Teams assigned to a project" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^project_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Project was already assigned" }, "201": { "description": "Project assigned" } }, "security": [ { "cookieAuth": [] } ], "summary": "Assign an owned project to a Team the owner administers" } }, "/v1/workspace/projects/{id}/teams/{teamId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Team assignment removed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Remove an owned project from a Team the owner administers" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^project_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "teamId", "required": true, "schema": { "pattern": "^team_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/projects:batch-family-update": { "post": { "description": "Locks and validates every account-owned project and its exact current revision before any write. The whole batch rolls back when any project is missing, stale, or has invalid stored data. Only data.family and data.familyNavigation can be changed.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WorkspaceProjectFamilyBatchRequest" }, { "$ref": "#/components/schemas/WorkspaceProjectGroupRequest" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceWebResponse" }, { "$ref": "#/components/schemas/WorkspaceProjectGroupResponse" } ] } } }, "description": "Updated projects or persistent project group operation result" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid, empty, duplicate, or oversized batch metadata" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Login required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "At least one project is not owned by this account or does not exist" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "At least one revision changed or stored project data is invalid; no project was updated" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Request body exceeds 128 KiB" } }, "security": [ { "cookieAuth": [] } ], "summary": "Atomically update family metadata across owned projects" } }, "/v1/workspace/runs": { "get": { "parameters": [ { "in": "query", "name": "sessionId", "required": false, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSessionRunResponse" } } }, "description": "Recent account-owned runs" } }, "security": [ { "cookieAuth": [] } ], "summary": "List recent account-owned Workspace session runs" } }, "/v1/workspace/runs/{runId}": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSessionRunResponse" } } }, "description": "Session run" }, "404": { "description": "Run not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read one account-owned Workspace session run" }, "parameters": [ { "in": "path", "name": "runId", "required": true, "schema": { "pattern": "^run_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/runs/{runId}/{action}": { "parameters": [ { "in": "path", "name": "runId", "required": true, "schema": { "pattern": "^run_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "heartbeat", "confirm", "complete", "cancel", "move-project", "context", "context-read" ], "type": "string" } } ], "post": { "description": "Heartbeats renew a short browser executor lease. Confirm, complete and context uploads are executor-bound; cancel is an account-owner action. Expired active runs become interrupted. The context action accepts clientExecutorId and data (base64, at most 262144 decoded bytes) and saves an immutable SHA-256-addressed chunk. The context-read action accepts digest and returns that chunk only to the account that owns this run. Clients retain context references in their checkpoint and opt in with snapshot.workspaceContextVersion equal to 1. Uploaded chunks alone do not advance progress or authorize a tool call.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WorkspaceSessionRunResponse" }, { "$ref": "#/components/schemas/WorkspaceSessionContextResponse" } ] } } }, "description": "Updated session run, or a saved context chunk receipt" }, "400": { "description": "Invalid action payload or context digest" }, "404": { "description": "Run or context chunk not found in this account" }, "409": { "description": "Run is no longer active or executor ownership changed" }, "413": { "description": "Run context storage capacity exceeded; existing work remains saved" } }, "security": [ { "cookieAuth": [] } ], "summary": "Advance an account-owned browser-executed Workspace run" } }, "/v1/workspace/secrets": { "get": { "description": "Returns names, kinds, environment-variable names, binding counts, and revisions. Values and ciphertext never appear in this response.", "responses": { "200": { "description": "Metadata-only Secret list" } }, "security": [ { "cookieAuth": [] } ], "summary": "List account-owned Workspace Secret metadata" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Secret metadata; the value is not returned" } }, "security": [ { "cookieAuth": [] } ], "summary": "Store an encrypted account-owned Workspace Secret" } }, "/v1/workspace/secrets/{id}": { "delete": { "parameters": [ { "in": "query", "name": "revision", "required": true, "schema": { "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Secret deleted" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete a Workspace Secret and its private Agent/App bindings" }, "get": { "responses": { "200": { "description": "Metadata-only Secret record" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read Workspace Secret metadata" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^secret_[a-f0-9]{24}$", "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Updated metadata-only Secret record" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update metadata or rotate a Workspace Secret value" } }, "/v1/workspace/secrets/{id}/bindings": { "get": { "responses": { "200": { "description": "Account-private binding list" } }, "security": [ { "cookieAuth": [] } ], "summary": "List private Agent/App references attached to a Secret" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^secret_[a-f0-9]{24}$", "type": "string" } } ], "put": { "description": "Bindings contain only account-scoped Secret IDs; no value is copied into an Agent or App. Marketplace-imported Agents and published Apps cannot be attached.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Updated account-private binding list" } }, "security": [ { "cookieAuth": [] } ], "summary": "Replace private Agent/App references attached to a Secret" } }, "/v1/workspace/secrets/{id}/project-file": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^secret_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Requires the signed-in Workspace, an active Session run in the same account-owned project, project_file permission on the Secret, and exact Secret/file revisions. Inserts a safely escaped value into a template without returning plaintext. The copy is an ordinary durable project file; rotation does not update existing copies.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "encoding": { "enum": [ "python", "json", "raw" ], "type": "string" }, "expectedRevision": { "minimum": 0, "type": "integer" }, "overwrite": { "default": false, "type": "boolean" }, "path": { "type": "string" }, "projectId": { "type": "string" }, "runId": { "type": "string" }, "secretRevision": { "minimum": 1, "type": "integer" }, "sessionId": { "type": "string" }, "template": { "description": "Text containing {{WORKSPACE_SECRET}}. Do not quote the placeholder for python or json encoding.", "type": "string" } }, "required": [ "sessionId", "runId", "projectId", "path", "template", "encoding", "secretRevision", "expectedRevision" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Value-free file revision receipt" }, "403": { "description": "Secret or project access is not authorized" }, "409": { "description": "Revision conflict or unverified completion; reconcile before retrying" } }, "security": [ { "cookieAuth": [] } ], "summary": "Copy a Workspace Secret into an owner project file" } }, "/v1/workspace/secrets/{id}/reveal": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^secret_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Available only to the signed-in Workspace web or desktop client, not generic API/curl, Agent, or hosted App callers. The action is rate-limited and audited. Responses are marked no-store and are never used as Agent or App model context.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Owner-only plaintext reveal" }, "429": { "description": "Reveal rate limit reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Explicitly reveal a Workspace Secret to its authenticated owner" } }, "/v1/workspace/services": { "get": { "responses": { "200": { "description": "Service status or result" }, "202": { "description": "Service start or stop accepted" }, "400": { "description": "Invalid command", "limits": null, "or request": null, "port": null }, "403": { "description": "Account or project access denied" }, "409": { "active project service": null, "description": "Service not ready", "or compute unavailable": null } }, "security": [ { "cookieAuth": [] } ], "summary": "List or start private project HTTP services" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Service status or result" }, "202": { "description": "Service start or stop accepted" }, "400": { "description": "Invalid command", "limits": null, "or request": null, "port": null }, "403": { "description": "Account or project access denied" }, "409": { "active project service": null, "description": "Service not ready", "or compute unavailable": null } }, "security": [ { "cookieAuth": [] } ], "summary": "List or start private project HTTP services" } }, "/v1/workspace/services/{serviceId}": { "get": { "responses": { "200": { "description": "Service status or result" }, "202": { "description": "Service start or stop accepted" }, "400": { "description": "Invalid command", "limits": null, "or request": null, "port": null }, "403": { "description": "Account or project access denied" }, "409": { "active project service": null, "description": "Service not ready", "or compute unavailable": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Read private service status, logs, and usage" }, "parameters": [ { "in": "path", "name": "serviceId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/services/{serviceId}/{action}": { "parameters": [ { "in": "path", "name": "serviceId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "stop", "preview", "request" ], "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Service status or result" }, "202": { "description": "Service start or stop accepted" }, "400": { "description": "Invalid command", "limits": null, "or request": null, "port": null }, "403": { "description": "Account or project access denied" }, "409": { "active project service": null, "description": "Service not ready", "or compute unavailable": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Stop, preview, or request an exact private service" } }, "/v1/workspace/session-outcomes": { "get": { "operationId": "workspaceSessionOutcomesRead", "parameters": [ { "in": "query", "name": "sessionId", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "runId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verified result with source digest and current assessment" }, "400": { "description": "Invalid identifiers" }, "401": { "description": "Login required" }, "404": { "description": "Owned finished default-agent result unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read the original finished default-agent chat result and its assessment" }, "post": { "description": "Requires the original session and run, source digest, expected assessment revision and an idempotency request key. Optional learning creates editable project Experience. Does not create a specialist version, affect version monitoring or rerun work.", "operationId": "workspaceSessionOutcomesSave", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Immutable receipt and current assessment" }, "400": { "description": "Invalid review" }, "401": { "description": "Login required" }, "403": { "description": "Project learning unavailable to this account" }, "404": { "description": "Original result unavailable" }, "409": { "description": "Source or assessment changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Record an owner assessment of a default-agent chat" } }, "/v1/workspace/sessions/{id}/agent-self": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } }, { "in": "header", "name": "X-Workspace-Agent-Capability", "required": true, "schema": { "maxLength": 4096, "minLength": 1, "type": "string" } } ], "patch": { "description": "The capability, account, session, active run, and personal Agent are rebound transactionally. Marketplace Agents and arbitrary metadata keys are rejected.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgentSelfUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Active personal Agent metadata updated" }, "409": { "active run": null, "description": "Agent", "or revision changed": null, "project access": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Update only safe metadata on the personal Agent active in this session run" } }, "/v1/workspace/sessions/{id}/agent-self/capability": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "The service derives the Agent and current project from the account-owned active run. My Agent is identified as base-agent and can edit current-project Skills; its profile is still updated through account preferences. The capability is short-lived and must be kept outside model arguments and results.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgentSelfCapabilityResponse" } } }, "description": "Short-lived active-Agent capability" }, "409": { "description": "No eligible active Agent run or project access changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Mint an opaque capability for My Agent or the personal Agent active in this session run" } }, "/v1/workspace/sessions/{id}/agent-skills": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } }, { "in": "header", "name": "X-Workspace-Agent-Capability", "required": true, "schema": { "maxLength": 4096, "minLength": 1, "type": "string" } } ], "post": { "description": "Project owner and scope are server-derived. The caller must retain live project owner/admin authority through commit.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgentSkillCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Project Skill created" }, "409": { "description": "Named-project edit authority or active run changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a Skill in the active session's named project" } }, "/v1/workspace/sessions/{id}/agent-skills/{skillId}": { "delete": { "parameters": [ { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Project Skill deleted" }, "404": { "description": "Skill is not in the active project" }, "409": { "active run": null, "description": "Project edit authority", "or Skill revision changed": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete a Skill from the active session's named project" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "skillId", "required": true, "schema": { "pattern": "^skill_[a-f0-9]{24}$", "type": "string" } }, { "in": "header", "name": "X-Workspace-Agent-Capability", "required": true, "schema": { "maxLength": 4096, "minLength": 1, "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceAgentSkillUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Project Skill updated" }, "404": { "description": "Skill is not in the active project" }, "409": { "active run": null, "description": "Project edit authority", "or Skill revision changed": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Update a Skill in the active session's named project" } }, "/v1/workspace/sessions/{id}/messages": { "get": { "parameters": [ { "description": "Opt into paged history, including messages older than the latest 500.", "in": "query", "name": "limit", "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "nextCursor from the previous page, scoped to this account and session.", "in": "query", "name": "before", "schema": { "type": "string" } }, { "description": "Read one exact message in this session. Cannot be combined with before.", "in": "query", "name": "messageId", "schema": { "type": "string" } }, { "description": "Messages strictly newer than this id, oldest first (v52), for incremental polling. Cannot be combined with before or messageId.", "in": "query", "name": "after", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Chronological messages. Without query parameters, returns the latest 500. Paged requests return nextCursor and hasMore for older history." } }, "security": [ { "cookieAuth": [] } ], "summary": "Read the retained transcript for an account-owned workspace session" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Transcript writes are append-only. Appending also advances the session revision and updated timestamp.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebMessageCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Message appended" } }, "security": [ { "cookieAuth": [] } ], "summary": "Append one message to an account-owned workspace session" } }, "/v1/workspace/sessions/{id}/runs": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSessionRunResponse" } } }, "description": "Recent session runs" } }, "security": [ { "cookieAuth": [] } ], "summary": "List recent browser-executed runs for one account-owned Workspace session" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Creates a leased account-scoped run record. A session may have one active run and an account may have three. The website remains the executor; this endpoint never grants computer use or DevOps access.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSessionRunCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSessionRunResponse" } } }, "description": "Run registered" }, "409": { "description": "This session already has an active run" }, "429": { "description": "Account concurrent run limit reached" } }, "security": [ { "cookieAuth": [] } ], "summary": "Register one browser-executed Workspace session run" } }, "/v1/workspace/sessions/{id}/shares": { "get": { "responses": { "200": { "description": "Active-first Session share records; bearer tokens are never returned by listing" } }, "security": [ { "cookieAuth": [] } ], "summary": "List owner-managed account-gated links for one Session" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Captures up to 500 user and assistant messages at the exact reviewed Session revision. System prompts, tool messages, metadata, attachments, project membership, Agents, Skills, secrets, approvals, and live browser or desktop state are excluded. The response returns a 256-bit shareToken exactly once for a client-side URL fragment.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedSessionRevision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expectedSessionRevision" ], "type": "object" } } }, "required": true }, "responses": { "201": { "description": "Immutable Session snapshot link created" }, "409": { "already has an active link": null, "description": "Session changed", "or account share limit reached": null }, "413": { "description": "Visible transcript exceeds the snapshot limit" }, "429": { "description": "Session share creation rate limited" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create an account-gated snapshot link for one Session" } }, "/v1/workspace/sessions/{id}/shares/{shareId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Session link revoked; recipient-owned copies already claimed remain independent" }, "409": { "description": "Session share changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Revoke an account-gated Session link at an exact share revision" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^session_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "shareId", "required": true, "schema": { "pattern": "^workspace_session_share_[a-f0-9]{24}$", "type": "string" } }, { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ] }, "/v1/workspace/shared": { "get": { "parameters": [ { "in": "query", "name": "direction", "schema": { "default": "incoming", "enum": [ "incoming", "outgoing", "all" ], "type": "string" } }, { "description": "Opaque signed continuation cursor scoped to this account and direction", "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 512, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileSharesResponse" } } }, "description": "Active-first revalidated private share page; incoming contains active authorized rows only and nextCursor continues the same account-scoped query" }, "400": { "description": "Invalid or cross-scope cursor" } }, "security": [ { "cookieAuth": [] } ], "summary": "List authorized incoming or owner-managed outgoing private files" } }, "/v1/workspace/shared-apps": { "get": { "responses": { "200": { "description": "Active claimed App shares without bearer preview URLs" } }, "security": [ { "cookieAuth": [] } ], "summary": "List active App versions shared with the signed-in account" } }, "/v1/workspace/shared-apps/{shareId}/open": { "parameters": [ { "in": "path", "name": "shareId", "required": true, "schema": { "pattern": "^workspace_resource_share_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Shared App metadata and short-lived preview URL" }, "404": { "description": "Shared App revoked or unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Open a claimed App share with a five-minute signed preview URL" } }, "/v1/workspace/shared-links/redeem": { "post": { "description": "Accepts the 256-bit fragment token in the authenticated request body, compares its SHA-256 hash in constant time, and records an idempotent per-viewer claim. Invalid, expired-by-revocation, ineligible, and mismatched links return the same non-disclosing 404. The raw token is never accepted in a URL or persisted by the service.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "shareId": { "pattern": "^workspace_share_[a-f0-9]{24}$", "type": "string" }, "shareToken": { "description": "Base64url encoding of 32 random bytes taken from the client-side URL fragment", "maxLength": 43, "minLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "shareId", "shareToken" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileSharesResponse" } } }, "description": "Link redeemed, including when this signed-in viewer had already redeemed it" }, "400": { "description": "Malformed request body" }, "404": { "description": "Shared file not found" }, "429": { "description": "Redemption rate limited" } }, "security": [ { "cookieAuth": [] } ], "summary": "Redeem an account-gated private file link for the signed-in user" } }, "/v1/workspace/shared-resource-links/redeem": { "post": { "description": "With previewOnly, returns the authorized Agent and Skill review without importing. Confirmed Agent imports atomically create recipient-owned Skills and an editable definition. App links create a revocable account-scoped claim to one exact runnable deployment.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "expectedSnapshotRevision": { "description": "Reviewed agent version; required to import a Skill bundle", "format": "int64", "minimum": 1, "type": "integer" }, "previewOnly": { "default": false, "type": "boolean" }, "shareId": { "pattern": "^workspace_resource_share_[a-f0-9]{24}$", "type": "string" }, "shareToken": { "maxLength": 43, "minLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "shareId", "shareToken" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Recipient-owned Agent or account-scoped App claim created or returned" }, "404": { "description": "Shared resource unavailable" }, "409": { "description": "Recipient resource limit reached" }, "429": { "description": "Redemption rate limited" } }, "security": [ { "cookieAuth": [] } ], "summary": "Redeem an account-gated Agent or App link" } }, "/v1/workspace/shared-session-links/redeem": { "post": { "description": "Validates the fragment token in constant time and idempotently creates one recipient-owned continuation. Only the snapshotted user and assistant text is copied. Reopening the same link returns the same imported Session; later recipient messages never change the sender's original.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "shareId": { "pattern": "^workspace_session_share_[a-f0-9]{24}$", "type": "string" }, "shareToken": { "maxLength": 43, "minLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": [ "shareId", "shareToken" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Recipient-owned Session created or existing idempotent claim returned" }, "404": { "description": "Shared Session unavailable" }, "409": { "description": "Session limit reached" }, "429": { "description": "Redemption rate limited" } }, "security": [ { "cookieAuth": [] } ], "summary": "Redeem an account-gated Session link into a recipient-owned Session" } }, "/v1/workspace/shared/{shareId}/download": { "get": { "responses": { "200": { "description": "Forced-attachment private file stream" }, "206": { "description": "Forced-attachment partial file stream" }, "404": { "deleted": null, "description": "Share revoked", "or no longer authorized": null }, "416": { "description": "Requested range is unavailable" }, "502": { "description": "Private runtime content is temporarily unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Stream a revalidated private file as a same-origin forced attachment" }, "parameters": [ { "in": "path", "name": "shareId", "required": true, "schema": { "pattern": "^workspace_share_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/shared/{shareId}/preview": { "get": { "responses": { "200": { "description": "Hardened inert text or safe raster preview stream" }, "206": { "description": "Hardened partial preview stream" }, "404": { "deleted": null, "description": "Share revoked", "or no longer authorized": null }, "413": { "description": "File is too large to preview" }, "416": { "description": "Requested range is unavailable" }, "502": { "description": "Private runtime content is temporarily unavailable" } }, "security": [ { "cookieAuth": [] } ], "summary": "Stream a revalidated private file through a same-origin ACL-bound proxy" }, "parameters": [ { "in": "path", "name": "shareId", "required": true, "schema": { "pattern": "^workspace_share_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/skills/{id}/impact": { "get": { "description": "Read-only version 1 inventory at the exact current Skill revision. Includes owned saved Agent attachments, selected and retained versions, direct Session attachments and admitted active task/job references, subject to current project access. Each group has a count and up to 20 entries; section and offset select the group to page. References can change after this read and do not prove the Skill ran. No instructions or private packages are exposed.", "operationId": "workspaceSkillImpactRead", "parameters": [ { "description": "Owned library Skill ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Exact current Skill revision", "in": "query", "name": "revision", "required": true, "schema": { "type": "string" } }, { "description": "agents, selectedVersions, sessions, activeTasks, activeJobs or retainedVersions; defaults to agents", "in": "query", "name": "section", "required": false, "schema": { "type": "string" } }, { "description": "Zero-based page offset for the selected section; defaults to 0", "in": "query", "name": "offset", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Versioned Skill impact with exact revision and paged reference groups" }, "400": { "description": "Invalid source revision or page" }, "401": { "description": "Login required" }, "404": { "description": "Skill was deleted or project access is unavailable" }, "409": { "description": "Skill revision changed" }, "500": { "description": "Skill impact could not be checked" } }, "security": [ { "cookieAuth": [] } ], "summary": "Review current Skill references and retained versions" } }, "/v1/workspace/storage-policy": { "get": { "operationId": "workspaceStoragePolicy", "responses": { "200": { "description": "Success" }, "401": { "description": "Authentication required" }, "404": { "description": "Resource unavailable or not authorized" }, "409": { "description": "Source revision or job state changed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read pooled workspace storage and video upload limits" } }, "/v1/workspace/subscription": { "get": { "description": "Returns the buyer's confirmed paid capacity, license/account status, email delivery states, and invitations for the signed-in verified email. Organization scope is rejected.", "responses": { "200": { "description": "Subscription overview with licenses, invitations, and assigned licenses" }, "401": { "description": "Sign in required" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read personal subscription and license assignments" }, "post": { "description": "Invites reserve one paid seat for seven days. Acceptance requires the invited verified email. Removing a license does not change Stripe billing or delete Workspace data. Cookie mutations require CSRF protection.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "invite", "resend", "revoke", "accept", "decline" ], "type": "string" }, "email": { "format": "email", "type": "string" }, "id": { "type": "string" } }, "required": [ "action" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "License mutation committed" }, "400": { "description": "Invalid request or organization scope" }, "401": { "description": "Sign in required" }, "409": { "description": "Unavailable invitation, paid capacity, or account eligibility" }, "429": { "description": "Invitation delivery cooldown or rate limit" } }, "security": [ { "cookieAuth": [] } ], "summary": "Manage personal subscription license invitations" } }, "/v1/workspace/teams": { "get": { "description": "Browser cookie sessions must traverse the signed Workspace edge. The desktop app uses an API-mode account token.", "responses": { "200": { "description": "Team list" } }, "security": [ { "cookieAuth": [] } ], "summary": "List Teams available to the authenticated Workspace account" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "Team created" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create a Team" } }, "/v1/workspace/teams/invitations/{invitationId}": { "parameters": [ { "in": "path", "name": "invitationId", "required": true, "schema": { "pattern": "^invite_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "action": { "enum": [ "accept", "decline" ], "type": "string" } }, "required": [ "action" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Invitation response saved" } }, "security": [ { "cookieAuth": [] } ], "summary": "Accept or decline an invitation for your verified email" } }, "/v1/workspace/teams/{teamId}": { "get": { "responses": { "200": { "description": "Team detail" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read Team members, shared projects, linked Rooms, and external agents" }, "parameters": [ { "in": "path", "name": "teamId", "required": true, "schema": { "pattern": "^team_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/teams/{teamId}/agents/{agentId}/keys": { "parameters": [ { "in": "path", "name": "teamId", "required": true, "schema": { "pattern": "^team_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^teamagent_[a-f0-9]{24}$", "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "201": { "description": "One-time Team agent key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Revoke the old external agent key and return a replacement once" } }, "/v1/workspace/teams/{teamId}/{action}": { "get": { "responses": { "200": { "description": "Team library or activity" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read Team library, recent Team audit, or project activity" }, "parameters": [ { "in": "path", "name": "teamId", "required": true, "schema": { "pattern": "^team_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "members", "projects", "rooms", "agents", "events", "library", "settings", "leave", "ownership", "delete", "invites", "audit" ], "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Team library version published or Team management action saved" }, "201": { "description": "Team resource created" }, "202": { "description": "In-app invitation created for explicit acceptance by its verified email account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Invite a member, publish a library version, share a resource, or manage Team settings" } }, "/v1/workspace/teams/{teamId}/{action}/{resourceId}": { "delete": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Team resource removed" } }, "security": [ { "cookieAuth": [] } ], "summary": "Remove a member or shared resource, cancel an invitation, or archive a library item" }, "parameters": [ { "in": "path", "name": "teamId", "required": true, "schema": { "pattern": "^team_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "members", "projects", "rooms", "agents", "library", "invites" ], "type": "string" } }, { "in": "path", "name": "resourceId", "required": true, "schema": { "maxLength": 160, "type": "string" } } ], "patch": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Team member or resource updated" } }, "security": [ { "cookieAuth": [] } ], "summary": "Change a member role or publish a revision-fenced Team resource update" }, "post": { "description": "Requires expectedRevision. Returns an editable personal copy, with all attached Skills for an Agent. A repeat of the same item and version returns the existing personal copy.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Version already added; existing personal copy returned" }, "201": { "copied atomically": null, "description": "Agent and attached Skills", "or Skill": null }, "409": { "description": "Review the changed Team version before adding" } }, "security": [ { "cookieAuth": [] } ], "summary": "Add a published Team library version to your Workspace" } }, "/v1/workspace/todos": { "get": { "operationId": "WorkspaceTodosGet", "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "projectId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "agentId", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "includeArchived", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "List the durable Workspace to-do list" }, "post": { "operationId": "WorkspaceTodosPost", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTodoWrite" } } }, "required": true }, "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Add a Workspace task" } }, "/v1/workspace/todos/{todoId}": { "delete": { "operationId": "WorkspaceTodoDelete", "parameters": [ { "in": "path", "name": "todoId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTodoWrite" } } }, "required": true }, "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Archive a task; retain it for restore" }, "get": { "operationId": "WorkspaceTodoGet", "parameters": [ { "in": "path", "name": "todoId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read a task and current revision" }, "patch": { "operationId": "WorkspaceTodoPatch", "parameters": [ { "in": "path", "name": "todoId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTodoWrite" } } }, "required": true }, "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Edit supplied task fields with revision check" } }, "/v1/workspace/todos/{todoId}/deliverables": { "post": { "operationId": "WorkspaceTodoDeliverablesPost", "parameters": [ { "in": "path", "name": "todoId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTodoWrite" } } }, "required": true }, "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Attach an exact saved file revision" } }, "/v1/workspace/todos/{todoId}/notes": { "post": { "operationId": "WorkspaceTodoNotesPost", "parameters": [ { "in": "path", "name": "todoId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTodoWrite" } } }, "required": true }, "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Append a task note" } }, "/v1/workspace/todos/{todoId}/restore": { "post": { "operationId": "WorkspaceTodoRestorePost", "parameters": [ { "in": "path", "name": "todoId", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceTodoWrite" } } }, "required": true }, "responses": { "200": { "description": "Workspace task result" }, "400": { "description": "Invalid task input" }, "401": { "description": "Sign in required" }, "403": { "description": "Workspace access denied" }, "404": { "description": "Task or linked resource unavailable" }, "409": { "description": "Stale revision or conflicting idempotency key" } }, "security": [ { "cookieAuth": [] } ], "summary": "Restore an archived task" } }, "/v1/workspace/tool-runs": { "get": { "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "List the latest 50 account-owned tool runs" }, "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCustomToolRunRequest" } } }, "required": true }, "responses": { "202": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Queue an idempotent tool run with exact resources and approvals" } }, "/v1/workspace/tool-runs/{runId}": { "get": { "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Read run status, result, call tree and bounded logs" }, "parameters": [ { "in": "path", "name": "runId", "required": true, "schema": { "type": "string" } } ] }, "/v1/workspace/tool-runs/{runId}/{action}": { "parameters": [ { "in": "path", "name": "runId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "action", "required": true, "schema": { "enum": [ "approve", "cancel" ], "type": "string" } } ], "post": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Invalid definition or input" }, "403": { "description": "Resource or capability access denied" }, "409": { "description": "Revision conflict", "disabled dependency": null, "or stopped run": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Approve or cancel an exact tool run" } }, "/v1/workspace/tools/web": { "post": { "description": "Executes web.fetch, confirmation-gated web.http, or bounded web.crawl for the hosted Secretary tool loop using the desktop fetch contract. Text and HTML responses include readable extraction, real links, final response metadata, and empty or JavaScript-shell classification; non-text responses retain metadata but withhold the body. Every request and redirect is DNS-resolved and rejects local, private, metadata, link-local, multicast, and reserved targets. The endpoint never receives provider credentials, cookies, or authorization headers, redacts response cookies, and never exposes computer use or DevOps.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "web.fetch", "web.http", "web.crawl" ], "type": "string" }, "body": {}, "followRedirects": { "type": "boolean" }, "headers": { "additionalProperties": { "maxLength": 1024, "type": "string" }, "type": "object" }, "maxPages": { "maximum": 12, "minimum": 1, "type": "integer" }, "method": { "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS" ], "type": "string" }, "sameSiteOnly": { "type": "boolean" }, "seeds": { "items": { "format": "uri", "maxLength": 4096, "type": "string" }, "maxItems": 10, "type": "array" }, "url": { "format": "uri", "maxLength": 4096, "type": "string" } }, "required": [ "action" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Structured desktop-compatible tool result; policy refusals and delivered HTTP failures are returned as ok false data" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid or unsupported tool request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Login required" } }, "security": [ { "cookieAuth": [] } ], "summary": "Execute one browser-safe public web tool" } }, "/v1/workspace/voice/context": { "post": { "description": "Resolves a saved session and active agent release; requires project editor access and an allowed hosted data boundary. Admission requires expectedRevision. Read-only operation=status requires agentId (empty for the base agent) and projectId (empty for General) and returns up to eight recent Live requests or active tasks, bounded progress and saved results. Reauthorizes on each read; never starts or resumes work. Does not authorize tool execution.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "agentId": { "type": "string" }, "expectedRevision": { "minimum": 1, "type": "integer" }, "operation": { "enum": [ "status" ], "type": "string" }, "projectId": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "sessionId" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Bounded voice context or read-only task status; taskStatusVersion=1 identifies durable Live request support" }, "403": { "description": "Project access denied" }, "409": { "description": "Changed session or restricted data boundary" } }, "security": [ { "cookieAuth": [] } ], "summary": "Resolve scoped voice conversation context" } }, "/v1/workspace/workflows/{workflowId}/runs": { "get": { "responses": { "200": { "description": "The newest 50 runs with their documents" } }, "security": [ { "cookieAuth": [] } ], "summary": "List a workflow's runs" }, "parameters": [ { "in": "path", "name": "workflowId", "required": true, "schema": { "pattern": "^workflow_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Validates the stored graph strictly (an invalid draft never starts) and queues a durable run advanced by the hosted worker. One active run per workflow.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Run queued", "with its id": null }, "409": { "description": "This workflow already has an active run" }, "422": { "description": "The graph is not runnable (validation messages included)" } }, "security": [ { "cookieAuth": [] } ], "summary": "Start a workflow run" } }, "/v1/workspace/workflows/{workflowId}/runs/{runId}": { "get": { "responses": { "200": { "description": "The run document" }, "404": { "description": "Run not found" } }, "security": [ { "cookieAuth": [] } ], "summary": "Get one workflow run" }, "parameters": [ { "in": "path", "name": "workflowId", "required": true, "schema": { "pattern": "^workflow_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "runId", "required": true, "schema": { "pattern": "^wfrun_[a-f0-9]{24}$", "type": "string" } } ] }, "/v1/workspace/workflows/{workflowId}/runs/{runId}/answer": { "parameters": [ { "in": "path", "name": "workflowId", "required": true, "schema": { "pattern": "^workflow_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "runId", "required": true, "schema": { "pattern": "^wfrun_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Feeds the operator's reply into an awaiting_input run. An ask-you gate stores the answer as its artifact; a blocked step re-runs with the input. Guarded so a concurrent answer cannot double-consume the gate.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "input": { "type": "string" }, "nodeId": { "description": "The gate this answer was written for; a run now waiting on a different gate returns 409", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Answer accepted", "run requeued": null }, "409": { "description": "The run is not waiting for input" } }, "security": [ { "cookieAuth": [] } ], "summary": "Answer a parked gate" } }, "/v1/workspace/workflows/{workflowId}/runs/{runId}/rewind": { "parameters": [ { "in": "path", "name": "workflowId", "required": true, "schema": { "pattern": "^workflow_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "runId", "required": true, "schema": { "pattern": "^wfrun_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Clones a NEW run from the source run's checkpoint at the given step and queues it. Only done/failed/stopped runs rewind; the one-active-run invariant still applies.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "nodeId": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The cloned run's id" }, "409": { "description": "The run is still live", "or another run is active": null, "the step has no checkpoint": null } }, "security": [ { "cookieAuth": [] } ], "summary": "Rewind a settled run" } }, "/v1/workspace/workflows/{workflowId}/runs/{runId}/stop": { "parameters": [ { "in": "path", "name": "workflowId", "required": true, "schema": { "pattern": "^workflow_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "runId", "required": true, "schema": { "pattern": "^wfrun_[a-f0-9]{24}$", "type": "string" } } ], "post": { "description": "Requests a stop; a live slice observes it at the next node boundary, and a parked run settles immediately.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" } ], "responses": { "200": { "description": "Stop requested" } }, "security": [ { "cookieAuth": [] } ], "summary": "Stop a workflow run" } }, "/v1/workspace/{collection}": { "get": { "parameters": [ { "in": "query", "name": "projectId", "required": false, "schema": { "pattern": "^project_[a-f0-9]{24}$", "type": "string" } }, { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Account-owned collection" } }, "security": [ { "cookieAuth": [] } ], "summary": "List one account-owned workspace collection" }, "parameters": [ { "$ref": "#/components/parameters/WorkspaceWebCollection" } ], "post": { "description": "Creates durable control-plane state only. Creation never performs a computer, DevOps, sandbox, app-publication, or connector side effect.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResourceWriteRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Workspace item created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Invalid item or project scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Collection quota reached or an Agent tag is already used in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create an account-owned workspace item" } }, "/v1/workspace/{collection}/{id}": { "delete": { "description": "Requires the current revision. Deleting a project reassigns its sessions and related workspace items to General rather than deleting their data.", "parameters": [ { "in": "query", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Workspace item deleted" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Revision changed; refresh before retrying" } }, "security": [ { "cookieAuth": [] } ], "summary": "Delete an account-owned workspace item" }, "get": { "parameters": [ { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Workspace item" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Item not found in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read an account-owned workspace item" }, "parameters": [ { "$ref": "#/components/parameters/WorkspaceWebCollection" }, { "in": "path", "name": "id", "required": true, "schema": { "pattern": "^(project|session|wiki|skill|agent|workflow|schedule)_[a-f0-9]{24}$", "type": "string" } } ], "patch": { "description": "expectedRevision is mandatory so two browser tabs cannot silently overwrite each other.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceCSRF" }, { "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResourceWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWebResponse" } } }, "description": "Workspace item updated" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Revision changed or an Agent tag is already used in this account" } }, "security": [ { "cookieAuth": [] } ], "summary": "Update an account-owned workspace item" } } }, "servers": [ { "url": "https://workspace.clankercloud.ai" } ], "x-source": { "file": "backend/openapi.yaml", "revision": "59f8c15475b8b381830afdb878dc0cbd77c82c62", "sha256": "2bd52961d4535d4032faf21798b1d5913fa23dccb1e4ae982fae34668120595d" } }