openapi: 3.0.3 info: title: Decision Terrain API version: 0.1.0 description: REST API reference for Decision Terrain agents, legacy browser-use automation tasks, webhooks, authentication, request parameters, and response schemas. paths: /agents/: get: operationId: listPersistentAgents parameters: - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaginatedPersistentAgentListList" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: List resources visible to this API key using page-number pagination. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get agents post: operationId: createPersistentAgent tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PersistentAgentDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PersistentAgentDetail" multipart/form-data: schema: $ref: "#/components/schemas/PersistentAgentDetail" security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Create an agent in the API key's owner scope; an Organization key creates in the issuer's Organization-private workspace. Active creation requests initial processing and, by default, a separate first-check-in timer even when the primary schedule is null. Use is_active=false to prepare a paused agent without initial processing publication or a first-check-in timer; metadata-generation jobs remain. Optional team_id uses current member/destination authority, requires Idempotency-Key and API_CONFIGURATION_ENABLED for fresh creation. template_code applies only on creation; see the Agent API guide for template and schedule precedence. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false parameters: - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Create an Agent /agents/{agentId}/attachments/{attachmentId}/download/: get: operationId: downloadAgentAttachment description: Download only a retained immutable message copy with exact G03 principal/message lineage and known scan provenance. No mutable filespace-node fallback; same bounded checksum snapshot and private response policy. Requires `agents:read`. Current principal/owner/filespace/origin authority is required. New local private intake requires API_REST_FILES_ENABLED and direct-upload scanning; admission defaults off. Active and pending generations remain separate; shared filespaces are not principal confidentiality compartments. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: attachmentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Files security: - ApiKeyAuth: [] responses: "200": content: application/octet-stream: schema: type: string format: binary description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Exact retained clean bytes are unavailable, corrupted or superseded. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Download Message Attachment Copy /agents/{agentId}/audit-runs/: get: operationId: listAgentAuditRuns description: Page safe retained Organization run metadata under current reporting authority and original ownership. Services require prospective runtime-start attribution; protected evidence is excluded. Requires `audit:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: as_of schema: type: string description: Optional creation watermark from a previous response; mutable values are not a snapshot. - in: query name: cursor schema: type: string description: Signed current-authority/filter-bound cursor, expires after 15 minutes; lists only. - in: query name: from schema: type: string description: Inclusive ISO8601 timestamp with offset. required: true - in: query name: include_evaluations schema: type: boolean description: Default false. Runs use original environment; legacy run exclusion requires a retained receipt not marked eval. - in: query name: limit schema: type: integer description: 1–100, default 50; list endpoints only. - in: query name: to schema: type: string description: Exclusive timestamp, at most 31 days after from and no later than now. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Audit metadata security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/RunPage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "410": description: Signed cursor expired; start a new inventory. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: Read gate, 10000-row selection bound, admission coordination or query deadline unavailable. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: audit:read x-service-credential-access: supported: true requiredScope: audit:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-deployment-gate: API_OPERATIONAL_READS_ENABLED x-retention: Currently retained authorized rows; absent records do not establish zero lifetime consumption. x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Agent Audit Runs /agents/{agentId}/audit-runs/{runId}/: get: operationId: getAgentAuditRun description: Read one authorized retained run metadata record inside a bounded time window. Recorded runtime status does not prove external success; no protected evidence or another principal request content is returned. Requires `audit:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: as_of schema: type: string description: Optional creation watermark from a previous response; mutable values are not a snapshot. - in: query name: from schema: type: string description: Inclusive ISO8601 timestamp with offset. required: true - in: query name: include_evaluations schema: type: boolean description: Default false. Runs use original environment; legacy run exclusion requires a retained receipt not marked eval. - in: path name: runId schema: type: string format: uuid required: true - in: query name: to schema: type: string description: Exclusive timestamp, at most 31 days after from and no later than now. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Audit metadata security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/RunMetadata" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "410": description: Signed cursor expired; start a new inventory. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: Read gate, 10000-row selection bound, admission coordination or query deadline unavailable. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: audit:read x-service-credential-access: supported: true requiredScope: audit:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-deployment-gate: API_OPERATIONAL_READS_ENABLED x-retention: Currently retained authorized rows; absent records do not establish zero lifetime consumption. x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent Audit Run /agents/{agentId}/configuration/: get: operationId: getAgentConfiguration parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ConfigurationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field patch: operationId: configureInactiveAgent parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: header name: If-Match schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedAgentConfigurationPatch" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedAgentConfigurationPatch" multipart/form-data: schema: $ref: "#/components/schemas/PatchedAgentConfigurationPatch" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ConfigurationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/events/: get: operationId: listAgentSourceEvents description: Read retained principal-scoped automatic source events with deterministic catch-up sequences, safe references and expiring cursors. Requires `agents:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: cursor schema: type: string - in: query name: inspect schema: type: boolean - in: query name: limit schema: type: integer - in: query name: request_id schema: type: string - in: query name: type schema: type: string - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent events security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/SourceEventPage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Agent Source Events /agents/{agentId}/files/: get: operationId: listAgentFiles description: List files in the default filespace, including nested files. Signed 24-hour cursors bind principal, owner, filespace and page size. Limit defaults 40 and is 1–100; inventory is not a snapshot. Requires `agents:read`. Current principal/owner/filespace/origin authority is required. New local private intake requires API_REST_FILES_ENABLED and direct-upload scanning; admission defaults off. Active and pending generations remain separate; shared filespaces are not principal confidentiality compartments. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: cursor schema: type: string - in: query name: limit schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Files security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentFilePage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Agent Files post: operationId: uploadAgentFile description: Stage one bounded multipart file in private quarantine. Required replay key binds exact bytes/name/parent/type. 202 is acceptance, not a clean verdict; poll detail. Size uses MAX_FILE_SIZE, 10 MiB/default and fallback. Requires `agents:operate`. Current principal/owner/filespace/origin authority is required. New local private intake requires API_REST_FILES_ENABLED and direct-upload scanning; admission defaults off. Active and pending generations remain separate; shared filespaces are not principal confidentiality compartments. parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Files requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/FileInput" required: true security: - ApiKeyAuth: [] responses: "202": content: application/json: schema: $ref: "#/components/schemas/AgentFile" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "415": description: File intake accepts multipart/form-data only. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. New public file intake also requires enabled private local storage and scanning admission. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: true requiredScope: agents:operate requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Upload Agent File /agents/{agentId}/files/{fileId}/: get: operationId: getAgentFile description: Read authorized availability, active/pending generation UUIDs and scan status. No scanner internals or storage locations are returned. Requires `agents:read`. Current principal/owner/filespace/origin authority is required. New local private intake requires API_REST_FILES_ENABLED and direct-upload scanning; admission defaults off. Active and pending generations remain separate; shared filespaces are not principal confidentiality compartments. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: fileId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Files security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentFile" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent File Status /agents/{agentId}/files/{fileId}/content/: put: operationId: replaceAgentFile description: Replace content of a stable file UUID with exactly one multipart file and a required replay key. Latest pending generation supersedes prior pending content; old clean bytes remain available until clean promotion. Requires `agents:operate`. Current principal/owner/filespace/origin authority is required. New local private intake requires API_REST_FILES_ENABLED and direct-upload scanning; admission defaults off. Active and pending generations remain separate; shared filespaces are not principal confidentiality compartments. parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: path name: fileId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Files requestBody: content: multipart/form-data: schema: $ref: "#/components/schemas/FileReplace" required: true security: - ApiKeyAuth: [] responses: "202": content: application/json: schema: $ref: "#/components/schemas/AgentFile" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "415": description: File intake accepts multipart/form-data only. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. New public file intake also requires enabled private local storage and scanning admission. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: true requiredScope: agents:operate requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Replace Agent File Content /agents/{agentId}/files/{fileId}/download/: get: operationId: downloadAgentFile description: Download an exact active generation after bounded checksum snapshot and final current-authority validation. Private octet-stream attachment with no-store/nosniff; no storage URL. Admitted HTTP bytes cannot be recalled. Requires `agents:read`. Current principal/owner/filespace/origin authority is required. New local private intake requires API_REST_FILES_ENABLED and direct-upload scanning; admission defaults off. Active and pending generations remain separate; shared filespaces are not principal confidentiality compartments. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: fileId schema: type: string format: uuid required: true - in: query name: generation_id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Files security: - ApiKeyAuth: [] responses: "200": content: application/octet-stream: schema: type: string format: binary description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Exact retained clean bytes are unavailable, corrupted or superseded. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Download Agent File Generation /agents/{agentId}/integrations/: get: operationId: listAgentIntegrations parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: kind schema: type: string enum: - native - openapi required: true - in: query name: page schema: type: integer - in: query name: page_size schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/integrations/{integrationId}/: get: operationId: getAgentIntegration parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: integrationId schema: type: string required: true - in: query name: kind schema: type: string enum: - native - openapi required: true - in: query name: page schema: type: integer - in: query name: page_size schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field patch: operationId: configureAgentIntegrationBinding parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: header name: If-Match schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: path name: integrationId schema: type: string required: true - in: query name: kind schema: type: string enum: - native - openapi required: true - in: query name: page schema: type: integer - in: query name: page_size schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedBinding" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedBinding" multipart/form-data: schema: $ref: "#/components/schemas/PatchedBinding" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/integrations/{integrationId}/setup/: get: operationId: getAgentIntegrationSetup parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: integrationId schema: type: string required: true - in: query name: kind schema: type: string enum: - native - openapi required: true - in: query name: page schema: type: integer - in: query name: page_size schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/readiness/: get: operationId: getAgentConfigurationReadiness parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: capability schema: type: string - in: query name: integration_id schema: type: string - in: query name: kind schema: type: string enum: - native - openapi - in: query name: operation_id schema: type: string - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/requests/: get: operationId: listApplicationRequests parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: cursor schema: type: string - in: query name: inspect schema: type: boolean - in: query name: limit schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Application requests security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ApplicationRequestPage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Principal-owned application resource intersected with current agent authority and original ownership. API_APPLICATION_REQUESTS_ENABLED defaults false for new admissions; reads and exact authorized replay remain available. Shared agents share model context; resource isolation does not establish generated-content confidentiality. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Application Requests post: operationId: createApplicationRequest parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Application requests requestBody: content: application/json: schema: $ref: "#/components/schemas/ApplicationRequestInput" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/ApplicationRequestInput" multipart/form-data: schema: $ref: "#/components/schemas/ApplicationRequestInput" required: true security: - ApiKeyAuth: [] responses: "202": content: application/json: schema: $ref: "#/components/schemas/ApplicationRequest" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:operate`. Principal-owned application resource intersected with current agent authority and original ownership. API_APPLICATION_REQUESTS_ENABLED defaults false for new admissions; reads and exact authorized replay remain available. Shared agents share model context; resource isolation does not establish generated-content confidentiality. x-required-api-key-scope: agents:operate x-service-credential-access: supported: true requiredScope: agents:operate requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: true concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Submit Application Request /agents/{agentId}/requests/{requestId}/: get: operationId: getApplicationRequest parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: inspect schema: type: boolean - in: path name: requestId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Application requests security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ApplicationRequest" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Principal-owned application resource intersected with current agent authority and original ownership. API_APPLICATION_REQUESTS_ENABLED defaults false for new admissions; reads and exact authorized replay remain available. Shared agents share model context; resource isolation does not establish generated-content confidentiality. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Application Request /agents/{agentId}/requests/{requestId}/responses/: get: operationId: listApplicationResponses parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: cursor schema: type: string - in: query name: inspect schema: type: boolean - in: query name: limit schema: type: integer - in: path name: requestId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Application requests security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ApplicationResponsePage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Principal-owned application resource intersected with current agent authority and original ownership. API_APPLICATION_REQUESTS_ENABLED defaults false for new admissions; reads and exact authorized replay remain available. Shared agents share model context; resource isolation does not establish generated-content confidentiality. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Application Responses /agents/{agentId}/requests/{requestId}/result/: get: operationId: getApplicationResult parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: inspect schema: type: boolean - in: path name: requestId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Application requests security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ApplicationResult" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Principal-owned application resource intersected with current agent authority and original ownership. API_APPLICATION_REQUESTS_ENABLED defaults false for new admissions; reads and exact authorized replay remain available. Shared agents share model context; resource isolation does not establish generated-content confidentiality. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Application Result /agents/{agentId}/requests/{requestId}/wait/: post: operationId: waitForApplicationRequest parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: requestId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Application requests requestBody: content: application/json: schema: $ref: "#/components/schemas/ApplicationRequestWait" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/ApplicationRequestWait" multipart/form-data: schema: $ref: "#/components/schemas/ApplicationRequestWait" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ApplicationWaitResult" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Principal-owned application resource intersected with current agent authority and original ownership. API_APPLICATION_REQUESTS_ENABLED defaults false for new admissions; reads and exact authorized replay remain available. Shared agents share model context; resource isolation does not establish generated-content confidentiality. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: true namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Wait for Application Request /agents/{agentId}/schedules/: get: operationId: listNamedSchedules parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Named schedules security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/SchedulePage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field post: operationId: createNamedSchedule parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Named schedules requestBody: content: application/json: schema: $ref: "#/components/schemas/ScheduleInput" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/ScheduleInput" multipart/form-data: schema: $ref: "#/components/schemas/ScheduleInput" required: true security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/Schedule" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/schedules/{scheduleId}/: get: operationId: getNamedSchedule parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: scheduleId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Named schedules security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/Schedule" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field patch: operationId: updateNamedSchedule parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: header name: If-Match schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: path name: scheduleId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Named schedules requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedSchedulePatch" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedSchedulePatch" multipart/form-data: schema: $ref: "#/components/schemas/PatchedSchedulePatch" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/Schedule" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field delete: operationId: deleteNamedSchedule parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: header name: If-Match schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: path name: scheduleId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Named schedules security: - ApiKeyAuth: [] responses: "204": description: No response body headers: Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/schedules/{scheduleId}/disable/: post: operationId: disableNamedSchedule parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: header name: If-Match schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: path name: scheduleId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Named schedules requestBody: content: application/json: schema: $ref: "#/components/schemas/EmptyInput" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/EmptyInput" multipart/form-data: schema: $ref: "#/components/schemas/EmptyInput" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/Schedule" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/schedules/{scheduleId}/enable/: post: operationId: enableNamedSchedule parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: header name: If-Match schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: path name: scheduleId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Named schedules requestBody: content: application/json: schema: $ref: "#/components/schemas/EmptyInput" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/EmptyInput" multipart/form-data: schema: $ref: "#/components/schemas/EmptyInput" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/Schedule" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{agentId}/usage/requests/: get: operationId: listAgentInferenceRequests description: Page authorized retained inference dispatch rows with original ownership, counters and pricing snapshots. Source request links are own-principal consumed executions only; protected content is omitted. Requires `usage:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: as_of schema: type: string description: Optional creation watermark from a previous response; mutable values are not a snapshot. - in: query name: cursor schema: type: string description: Signed current-authority/filter-bound cursor, expires after 15 minutes; lists only. - in: query name: from schema: type: string description: Inclusive ISO8601 timestamp with offset. required: true - in: query name: include_evaluations schema: type: boolean description: Default false. Runs use original environment; legacy run exclusion requires a retained receipt not marked eval. - in: query name: limit schema: type: integer description: 1–100, default 50; list endpoints only. - in: query name: to schema: type: string description: Exclusive timestamp, at most 31 days after from and no later than now. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Usage security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/UsagePage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "410": description: Signed cursor expired; start a new inventory. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: Read gate, 10000-row selection bound, admission coordination or query deadline unavailable. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: usage:read x-service-credential-access: supported: true requiredScope: usage:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-deployment-gate: API_OPERATIONAL_READS_ENABLED x-retention: Currently retained authorized rows; absent records do not establish zero lifetime consumption. x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Agent Inference Requests /agents/{agentId}/usage/summary/: get: operationId: getAgentUsageSummary description: Read bounded authorized retained dispatch totals with known token coverage and separate estimated/provider-reported USD subtotals. Requires explicit reporting authority; missing values remain unknown. Requires `usage:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: as_of schema: type: string description: Optional creation watermark from a previous response; mutable values are not a snapshot. - in: query name: from schema: type: string description: Inclusive ISO8601 timestamp with offset. required: true - in: query name: include_evaluations schema: type: boolean description: Default false. Runs use original environment; legacy run exclusion requires a retained receipt not marked eval. - in: query name: to schema: type: string description: Exclusive timestamp, at most 31 days after from and no later than now. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Usage security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/UsageSummary" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "410": description: Signed cursor expired; start a new inventory. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: Read gate, 10000-row selection bound, admission coordination or query deadline unavailable. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: usage:read x-service-credential-access: supported: true requiredScope: usage:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-deployment-gate: API_OPERATIONAL_READS_ENABLED x-retention: Currently retained authorized rows; absent records do not establish zero lifetime consumption. x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent Usage Summary /agents/{agentId}/webhooks/{webhookId}/deliveries/: get: operationId: listAgentWebhookDeliveries description: Inspect a currently managed subscription delivery ledger with scoped counts and sanitized failure diagnostics before cursor pagination. Requires `agents:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: query name: cursor schema: type: string - in: query name: inspect schema: type: boolean - in: query name: limit schema: type: integer - in: path name: webhookId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent events security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/DeliveryPage" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Webhook Deliveries /agents/{agentId}/webhooks/{webhookId}/deliveries/{deliveryId}/: get: operationId: getAgentWebhookDelivery description: Inspect sanitized immutable delivery attempts, recovery cycles, current revision and conditional recovery eligibility for an authorized subscription. Requires `agents:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: deliveryId schema: type: string format: uuid required: true - in: query name: inspect schema: type: boolean - in: path name: webhookId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent events security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/Delivery" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Webhook Delivery /agents/{agentId}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver/: post: operationId: redeliverAgentWebhookDelivery description: Deliberately recover one eligible failed or acknowledged unknown delivery at its expected revision, preserving event identity and prior evidence. Requires `agents:manage`. parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: path name: deliveryId schema: type: string format: uuid required: true - in: query name: inspect schema: type: boolean - in: path name: webhookId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent events requestBody: content: application/json: schema: $ref: "#/components/schemas/RedeliveryInput" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/RedeliveryInput" multipart/form-data: schema: $ref: "#/components/schemas/RedeliveryInput" required: true security: - ApiKeyAuth: [] responses: "202": content: application/json: schema: $ref: "#/components/schemas/Delivery" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Recover Webhook Delivery /agents/{agentId}/workspace/: patch: operationId: moveAgentWorkspace parameters: - in: header name: Idempotency-Key schema: type: string required: true - in: header name: If-Match schema: type: string required: true - in: path name: agentId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedPlacement" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedPlacement" multipart/form-data: schema: $ref: "#/components/schemas/PatchedPlacement" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/ConfigurationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. ETag: schema: type: string description: Exact resource/configuration revision for If-Match. Replayed ETags describe the original outcome. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Configuration revision changed; reload before using a new retry key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: If-Match is required for existing-resource mutations. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "configuration_unavailable: New REST configuration admission is disabled; authorized replay survives this gate. admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Suggested retry seconds when admission coordination is unavailable. configuration_unavailable requires deployment enablement and has no Retry-After interval. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:manage`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{id}/: get: operationId: getPersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. ETag: schema: type: string description: Strong agent configuration revision. Conditional replay returns the original ETag. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Retrieve one resource visible to this API key. Inaccessible resources return 404. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent put: operationId: updatePersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: Required for member or service conditional writes selected by X-API-Contract. Reuse the same key, version, body, query and If-Match; current authority precedes retained replay. Legacy service writes retain optional identity-scoped replay. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. - in: header name: If-Match required: false schema: type: string description: Required for conditional writes selected by X-API-Contract; If-Match without that version is rejected. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PersistentAgentDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PersistentAgentDetail" multipart/form-data: schema: $ref: "#/components/schemas/PersistentAgentDetail" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Selected conditional writes: false for original acceptance, true for an authorized historical replay." ETag: schema: type: string description: Strong agent configuration revision. Conditional replay returns the original ETag. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Changed retry key semantics. content: application/json: schema: $ref: "#/components/schemas/VersionedRestError" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Stale configuration revision; refresh state. content: application/json: schema: $ref: "#/components/schemas/VersionedRestError" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: Missing exact If-Match. content: application/json: schema: $ref: "#/components/schemas/VersionedRestError" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Update the supplied writable fields. Omitted optional fields retain their values; this does not reset the resource to defaults. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true mutableFields: - charter - contact_approval_mode - is_active - name - preferred_llm_tier - proactive_opt_in - schedule - whitelist_policy idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field conditionalUpdates: requiredHeaders: - X-API-Contract - If-Match - Idempotency-Key creationOnlyFields: - team_id - template_code unsupportedFields: - enabled_personal_server_ids revisionFields: - name - charter - schedule - is_active - life_state - proactive_opt_in - preferred_llm_tier - whitelist_policy - contact_approval_mode - email_sending_mode - preferred_contact_endpoint gate: API_CONFIGURATION_ENABLED unchangedWriteAdvancesRevision: false legacyWrites: Last write wins; advance the same revision. summary: Update Persistent Agent x-mint: metadata: sidebarTitle: Agent - Update patch: operationId: partialUpdatePersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: Required for member or service conditional writes selected by X-API-Contract. Reuse the same key, version, body, query and If-Match; current authority precedes retained replay. Legacy service writes retain optional identity-scoped replay. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. - in: header name: If-Match required: false schema: type: string description: Required for conditional writes selected by X-API-Contract; If-Match without that version is rejected. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedPersistentAgentDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedPersistentAgentDetail" multipart/form-data: schema: $ref: "#/components/schemas/PatchedPersistentAgentDetail" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Selected conditional writes: false for original acceptance, true for an authorized historical replay." ETag: schema: type: string description: Strong agent configuration revision. Conditional replay returns the original ETag. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Changed retry key semantics. content: application/json: schema: $ref: "#/components/schemas/VersionedRestError" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "412": description: Stale configuration revision; refresh state. content: application/json: schema: $ref: "#/components/schemas/VersionedRestError" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "428": description: Missing exact If-Match. content: application/json: schema: $ref: "#/components/schemas/VersionedRestError" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Update only supplied writable fields. Read-only and unknown fields are ignored by the model serializer. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true mutableFields: - charter - contact_approval_mode - is_active - name - preferred_llm_tier - proactive_opt_in - schedule - whitelist_policy idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field conditionalUpdates: requiredHeaders: - X-API-Contract - If-Match - Idempotency-Key creationOnlyFields: - team_id - template_code unsupportedFields: - enabled_personal_server_ids revisionFields: - name - charter - schedule - is_active - life_state - proactive_opt_in - preferred_llm_tier - whitelist_policy - contact_approval_mode - email_sending_mode - preferred_contact_endpoint gate: API_CONFIGURATION_ENABLED unchangedWriteAdvancesRevision: false legacyWrites: Last write wins; advance the same revision. summary: Patch Persistent Agent x-mint: metadata: sidebarTitle: Agent - Patch delete: operationId: deletePersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: "Service credentials only: identity-scoped retry key, retained for 24 hours by default. Rotation preserves the namespace; current scope and resource grants are rechecked before replay." - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "204": description: No response body headers: Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Archive the agent and release its communication endpoints. Use archived/ and restore/ to recover it. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Archive Agent x-mint: metadata: sidebarTitle: Agent - Archive /agents/{id}/activate/: post: operationId: activatePersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: "Service credentials only: identity-scoped retry key, retained for 24 hours by default. Rotation preserves the namespace; current scope and resource grants are rechecked before replay." - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentActivationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Activate the agent and clear expired state. The server may restore its saved schedule. No request body is needed; updated indicates whether state changed. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Activate Agent /agents/{id}/contact-endpoints/: get: operationId: listPersistentAgentContactEndpoints parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentContactEndpointListResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Discover the agent's persisted communication endpoints and current preferred endpoint before sending messages or changing contact preference. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Contact Endpoints /agents/{id}/contacts/: get: operationId: listPersistentAgentContacts parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: query name: include_inactive schema: type: string enum: - "0" - "1" - "false" - "true" default: "false" description: Include deactivated contacts. Values are case-insensitive; invalid values return 400. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentContactListResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: List active contacts and their communication permissions. Set include_inactive=true to include deactivated entries; returns contacts and count. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Agent Contacts post: operationId: createPersistentAgentContact parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentContactCreate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/AgentContactCreate" multipart/form-data: schema: $ref: "#/components/schemas/AgentContactCreate" required: true security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentContactMutationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "201": content: application/json: schema: $ref: "#/components/schemas/AgentContactMutationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Add or reactivate an email or web contact. An active contact selects manual allowlist policy. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Add or Reactivate Contact /agents/{id}/contacts/{contactId}/: get: operationId: getPersistentAgentContact parameters: - in: path name: contactId schema: type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentContactMutationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Read one contact and its inbound, outbound, configuration, and activation permissions. Contact channel and address are immutable. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent Contact patch: operationId: updatePersistentAgentContact parameters: - in: path name: contactId schema: type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedAgentContactUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedAgentContactUpdate" multipart/form-data: schema: $ref: "#/components/schemas/PatchedAgentContactUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentContactMutationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Update supplied contact permissions or is_active. To change channel or address, deactivate this contact and add a replacement. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Update Agent Contact delete: operationId: deactivatePersistentAgentContact parameters: - in: path name: contactId schema: type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentContactMutationResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Reversibly deactivate this contact while preserving its identity and history. Repeating deactivation is safe; return the updated contact. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Deactivate Agent Contact /agents/{id}/deactivate/: post: operationId: deactivatePersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: "Service credentials only: identity-scoped retry key, retained for 24 hours by default. Rotation preserves the namespace; current scope and resource grants are rechecked before replay." - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentActivationResponse" description: "" headers: Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Pause the agent without archiving it. No request body is needed; repeating the call returns updated=false once paused. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Deactivate Agent /agents/{id}/debug-trace/: get: operationId: getPersistentAgentDebugTrace description: Return a bounded, sanitized diagnostic trace for one agent. Raw prompt archives and secret-like values are never returned. Repeat `include` or use comma-separated values to select sections; use `recent_minutes=null` to disable the default recent window. Foreign, transferred or purged application history requires principal-scoped request reads. Requires `agents:read`. parameters: - in: query name: cursor schema: type: string nullable: true minLength: 1 - in: query name: detail schema: enum: - summary - standard - verbose type: string default: standard minLength: 1 description: |- * `summary` - summary * `standard` - standard * `verbose` - verbose - in: query name: eval_run_id schema: type: string format: uuid nullable: true - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: query name: include schema: type: array items: enum: - timeline - audit_events - completions - eval_debug_artifacts - diagnostics type: string description: |- * `timeline` - timeline * `audit_events` - audit_events * `completions` - completions * `eval_debug_artifacts` - eval_debug_artifacts * `diagnostics` - diagnostics default: - timeline - audit_events - completions - eval_debug_artifacts - diagnostics - in: query name: limit schema: type: integer maximum: 50 minimum: 1 default: 20 - in: query name: recent_minutes schema: type: integer maximum: 10080 minimum: 1 nullable: true - in: query name: since schema: type: string nullable: true minLength: 1 - in: query name: until schema: type: string nullable: true minLength: 1 - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentDebugTraceResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent Debug Trace x-mint: metadata: sidebarTitle: Agent Debug Trace - Get /agents/{id}/events/wait/: post: operationId: waitForPersistentAgentEvent description: Long-poll one agent's durable timeline for up to 30 seconds. Events are strictly newer than `after_cursor`; the response always returns the latest cursor for the next wait. This read-only operation requires `agents:read` even though it uses POST. Each snapshot rejects foreign, transferred or purged application history; use scoped request waits. Requires `agents:read`. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PersistentAgentEventWaitRequest" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PersistentAgentEventWaitRequest" multipart/form-data: schema: $ref: "#/components/schemas/PersistentAgentEventWaitRequest" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentEventWaitResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: true namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Wait for Agent Event x-mint: metadata: sidebarTitle: Agent Events - Wait /agents/{id}/inbound-webhooks/: get: operationId: listPersistentAgentInboundWebhooks parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentInboundWebhookListResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: List inbound webhook metadata without invocation URLs or secrets. Use the manage-scoped detail endpoint to obtain an invocation URL. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field post: operationId: createPersistentAgentInboundWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentInboundWebhookCreate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/AgentInboundWebhookCreate" multipart/form-data: schema: $ref: "#/components/schemas/AgentInboundWebhookCreate" required: true security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/AgentInboundWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Create a secret-bearing URL for external systems to trigger this agent. Invoking that URL uses a separate ingestion contract documented in Webhooks and events. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{id}/inbound-webhooks/{webhookId}/: get: operationId: getPersistentAgentInboundWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentInboundWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Retrieve one inbound webhook and its secret-bearing invocation URL. This credential-bearing read requires manage scope. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field patch: operationId: updatePersistentAgentInboundWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedAgentInboundWebhookUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedAgentInboundWebhookUpdate" multipart/form-data: schema: $ref: "#/components/schemas/PatchedAgentInboundWebhookUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentInboundWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Update the name or enabled state of an inbound webhook. Disabled webhooks reject invocation without storing an inbound message. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field delete: operationId: deletePersistentAgentInboundWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentInboundWebhookDeleteResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Delete an inbound webhook registration and invalidate its invocation URL. Previously accepted agent messages remain in history. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{id}/inbound-webhooks/{webhookId}/rotate-secret/: post: operationId: rotatePersistentAgentInboundWebhookSecret parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentInboundWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Replace the inbound webhook invocation secret immediately and return the replacement URL. External senders must switch to the new URL. Requires `agents:manage`. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{id}/messages/: post: operationId: sendPersistentAgentMessage parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PersistentAgentMessageCreate" examples: EmailInput: value: channel: email sender: owner@example.com body: Summarize today's work. summary: Email input application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PersistentAgentMessageCreate" multipart/form-data: schema: $ref: "#/components/schemas/PersistentAgentMessageCreate" required: true security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/AgentMessageResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": content: application/json: schema: type: object additionalProperties: true description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Ingest a message from an allowed sender using a supported channel and agent endpoint. Email is a supported input. Returns 201 with the stored timeline event, not an agent reply or proof of processing. Inactive agents return 409; disallowed senders return 403. REST does not accept file attachments here. Requires `agents:operate`. x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: true concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Message Agent /agents/{id}/peer-links/: get: operationId: listPersistentAgentPeerLinks description: List this agent's symmetric peer links, including disabled links. Requires agents:read. Requires `agents:read`. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PeerLinkListResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Peer Links x-mint: metadata: sidebarTitle: Peer Links - List post: operationId: createPersistentAgentPeerLink description: Create or re-enable a symmetric peer link. Requires agents:manage and access to both agents. Omitted quotas default to 30 messages per 6 hours, including for existing links. Requires `agents:manage`. parameters: - in: header name: Idempotency-Key schema: type: string description: Optional API-key-scoped retry key. Completed responses are replayed for 24 hours; different input returns 409. - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PeerLinkCreate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PeerLinkCreate" multipart/form-data: schema: $ref: "#/components/schemas/PeerLinkCreate" required: true security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PeerLinkCreateResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "201": content: application/json: schema: $ref: "#/components/schemas/PeerLinkCreateResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Create or Enable Peer Link x-mint: metadata: sidebarTitle: Peer Link - Create or Enable /agents/{id}/peer-links/{linkId}/: get: operationId: getPersistentAgentPeerLink description: Retrieve a peer link attached to this agent. Requires agents:read. Requires `agents:read`. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: linkId schema: type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PeerLinkResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Peer Link x-mint: metadata: sidebarTitle: Peer Link - Get patch: operationId: updatePersistentAgentPeerLink description: Edit peer-link quotas or enabled state without replenishing credits. Requires agents:manage. Requires `agents:manage`. parameters: - in: header name: Idempotency-Key schema: type: string description: Optional API-key-scoped retry key. Completed responses are replayed for 24 hours; different input returns 409. - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: linkId schema: type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedPeerLinkUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedPeerLinkUpdate" multipart/form-data: schema: $ref: "#/components/schemas/PatchedPeerLinkUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PeerLinkResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Update Peer Link x-mint: metadata: sidebarTitle: Peer Link - Update delete: operationId: deletePersistentAgentPeerLink description: Remove the peer link while preserving historical conversations and messages. Requires agents:manage. Requires `agents:manage`. parameters: - in: header name: Idempotency-Key schema: type: string description: Optional API-key-scoped retry key. Completed responses are replayed for 24 hours; different input returns 409. - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: linkId schema: type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "204": description: No response body headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Remove Peer Link x-mint: metadata: sidebarTitle: Peer Link - Remove /agents/{id}/pending-actions/: get: operationId: listPersistentAgentPendingActions parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PendingActionListResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: List visible unresolved decisions with typed IDs, data, and allowed_decisions. Includes human input, outbox review, spawn, secrets, contacts, and OpenAPI approvals. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Pending Actions /agents/{id}/pending-actions/{actionId}/resolve/: post: operationId: resolvePersistentAgentPendingAction parameters: - in: path name: actionId schema: type: string pattern: ^[^/]+$ required: true - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PendingActionResolveRequest" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PendingActionResolveRequest" multipart/form-data: schema: $ref: "#/components/schemas/PendingActionResolveRequest" required: true security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PendingActionResolveResponse" description: "" headers: Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: New protected admissions are unavailable; the header is never silently ignored. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:operate` for human_input and outbox_review; other action types require `agents:manage`. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded. x-required-api-key-scope: human_input: agents:operate outbox_review: agents:operate default: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Resolve Pending Action /agents/{id}/processing-status/: get: operationId: getPersistentAgentProcessingStatus parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentProcessingStatusResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Read current processing state and a snapshot of active browser tasks and the next known scheduled run. This does not wait for work to finish. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent Processing Status /agents/{id}/restore/: post: operationId: restorePersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: "Service credentials only: identity-scoped retry key, retained for 24 hours by default. Rotation preserves the namespace; current scope and resource grants are rechecked before replay." - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentRestoreResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentRestoreConflict" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Restore an archived agent and reclaim available endpoints and peer links. The agent remains inactive; a conflicting active name returns 409. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Restore Agent x-mint: metadata: sidebarTitle: Agent - Restore /agents/{id}/schedule/preview/: post: operationId: previewPersistentAgentSchedule parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PersistentAgentSchedulePreview" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PersistentAgentSchedulePreview" multipart/form-data: schema: $ref: "#/components/schemas/PersistentAgentSchedulePreview" required: true security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentSchedulePreviewResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Validate the primary recurring schedule without saving it. Returns valid, disabled, and a description; empty or null input previews an unscheduled agent. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Preview Agent Schedule /agents/{id}/stop/: post: operationId: stopPersistentAgent parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: "Service credentials only: identity-scoped retry key, retained for 24 hours by default. Rotation preserves the namespace; current scope and resource grants are rechecked before replay." - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersistentAgentStopResponse" description: "" headers: Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Request a graceful stop of current processing and cancel active browser tasks without deactivating the agent. Returns stopping state, cancellation count, and processing snapshot. Requires `agents:operate`. x-required-api-key-scope: agents:operate x-service-credential-access: supported: true requiredScope: agents:operate requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Stop Agent Work /agents/{id}/timeline/: get: operationId: getPersistentAgentTimeline description: Read the unified timeline using an opaque cursor and direction. Returns events, boundary cursors, pagination flags, and processing state. Nested event fields use camelCase; envelope fields use snake_case. Requires `agents:read`. parameters: - in: query name: cursor schema: type: string description: Opaque boundary cursor returned by a timeline event or response. - in: query name: direction schema: type: string enum: - initial - newer - older default: initial - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: query name: limit schema: type: integer default: 40 description: Page size; clamped to 1–100. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentTimelineResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Agent Timeline /agents/{id}/web-tasks/: get: operationId: listWebTasks parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: query name: limit schema: type: integer default: 50 description: Maximum tasks returned; clamped to 1–200. - in: query name: status schema: type: string enum: - cancelled - completed - failed - in_progress - pending - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentWebTasksResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: List recent browser tasks run by this persistent agent. This bounded results envelope uses limit and status, not page-number pagination. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Web Tasks /agents/{id}/webhooks/: get: operationId: listPersistentAgentWebhooks parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentWebhookListResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: List outbound webhook metadata and subscriptions. Destination URLs and signing secrets are omitted; use the manage-scoped detail endpoint for them. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field post: operationId: createPersistentAgentWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentWebhookCreate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/AgentWebhookCreate" multipart/form-data: schema: $ref: "#/components/schemas/AgentWebhookCreate" required: true security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/AgentWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Create an outbound webhook destination and return its signing secret. Select pending-action subscriptions explicitly; the default agent.message type describes explicit agent tool sends. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{id}/webhooks/{webhookId}/: get: operationId: getPersistentAgentWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Retrieve one outbound webhook, including its destination and signing secret. Treat this response as credentials; read-only keys cannot retrieve it. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field patch: operationId: updatePersistentAgentWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: "Service credentials only: identity-scoped retry key, retained for 24 hours by default. Rotation preserves the namespace; current scope and resource grants are rechecked before replay." - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedAgentWebhookUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedAgentWebhookUpdate" multipart/form-data: schema: $ref: "#/components/schemas/PatchedAgentWebhookUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Update supplied outbound webhook settings, including event subscriptions and enabled state. Returns the webhook's current configuration. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field delete: operationId: deletePersistentAgentWebhook parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: "Service credentials only: identity-scoped retry key, retained for 24 hours by default. Rotation preserves the namespace; current scope and resource grants are rechecked before replay." - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentWebhookDeleteResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Delete an outbound webhook registration so it is no longer available for future sends. Historical agent activity is not erased. Requires `agents:manage`. x-required-api-key-scope: agents:manage x-service-credential-access: supported: true requiredScope: agents:manage requiresInstallationAndOrganizationEnablement: true idempotencySupported: true x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/{id}/webhooks/{webhookId}/rotate-secret/: post: operationId: rotatePersistentAgentWebhookSecret parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this persistent agent. required: true - in: path name: webhookId schema: type: string pattern: ^[^/]+$ required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentWebhookResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Replace the outbound webhook signing secret immediately and return the new value. The sender does not provide a dual-secret grace period. Requires `agents:manage`. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded. x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /agents/archived/: get: operationId: listArchivedPersistentAgents parameters: - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaginatedPersistentAgentArchivedListList" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: List archived agents in this key's owner scope, using page and page_size. Archived agents are excluded from the ordinary collection. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Archived Agents x-mint: metadata: sidebarTitle: Archived Agents - List /agents/browser-use/: get: operationId: listAgents description: List resources visible to this API key using page-number pagination. Requires `agents:read`. parameters: - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaginatedAgentListList" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Legacy Browser-Use Agents x-mint: metadata: sidebarTitle: Legacy Browser-Use Agents - List post: operationId: createAgent description: Create a resource in the API key's owner scope. Read-only fields in the representation cannot be set by the client. Requires `agents:manage`. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/AgentDetail" multipart/form-data: schema: $ref: "#/components/schemas/AgentDetail" required: true security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/AgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false parameters: - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Create Legacy Browser-Use Agent x-mint: metadata: sidebarTitle: Legacy Browser-Use Agent - Create /agents/browser-use/{agentId}/tasks/: get: operationId: listTasks description: List resources visible to this API key using page-number pagination. Requires `agents:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaginatedTaskListList" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Legacy Agent Tasks x-mint: metadata: sidebarTitle: Legacy Agent Tasks - List post: operationId: assignTask description: Create a resource in the API key's owner scope. Read-only fields in the representation cannot be set by the client. Requires `agents:operate`. When API_ADMISSION_ENABLED is true, omit wait even without Idempotency-Key; queued-input capacity is shared across stable principal and owner. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/TaskDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/TaskDetail" multipart/form-data: schema: $ref: "#/components/schemas/TaskDetail" security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/TaskCreateResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "402": content: application/json: schema: $ref: "#/components/schemas/InsufficientCreditsResponse" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. task_secrets_unavailable: credential encryption is unavailable; no task secret/input changes were committed. This error has no Retry-After readiness interval." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: true concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false requiresAsyncSubmissionWhenEnabled: true x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Create Legacy Agent Task x-mint: metadata: sidebarTitle: Legacy Agent Task - Create /agents/browser-use/{agentId}/tasks/{id}/: get: operationId: getTask description: Retrieve one resource visible to this API key. Inaccessible resources return 404. Requires `agents:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Legacy Agent Task x-mint: metadata: sidebarTitle: Legacy Agent Task - Get put: operationId: updateTask description: Update supplied writable task inputs while pending and unclaimed. A supplied secrets map replaces all task credentials; {} clears them, omission preserves them, and null is invalid. Secret columns and other inputs commit atomically. A winning worker claim or cancellation rejects input edits with 400; deleted or retention-purged tasks return 404. Webhook-only edits remain available on retained running/terminal tasks. Responses never return credentials or key lists. Success acknowledges stored input, not execution or authentication. These updates have no credential readback, conditional revision or idempotency guarantee. Requires `agents:operate`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/TaskUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/TaskUpdate" multipart/form-data: schema: $ref: "#/components/schemas/TaskUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. task_secrets_unavailable: credential encryption is unavailable; no task secret/input changes were committed. This error has no Retry-After readiness interval." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Update Legacy Agent Task x-mint: metadata: sidebarTitle: Legacy Agent Task - Update patch: operationId: updateTaskStatusPartial description: Update supplied writable task inputs while pending and unclaimed. A supplied secrets map replaces all task credentials; {} clears them, omission preserves them, and null is invalid. Secret columns and other inputs commit atomically. A winning worker claim or cancellation rejects input edits with 400; deleted or retention-purged tasks return 404. Webhook-only edits remain available on retained running/terminal tasks. Responses never return credentials or key lists. Success acknowledges stored input, not execution or authentication. These updates have no credential readback, conditional revision or idempotency guarantee. Requires `agents:operate`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedTaskUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedTaskUpdate" multipart/form-data: schema: $ref: "#/components/schemas/PatchedTaskUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. task_secrets_unavailable: credential encryption is unavailable; no task secret/input changes were committed. This error has no Retry-After readiness interval." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Patch Legacy Agent Task x-mint: metadata: sidebarTitle: Legacy Agent Task - Patch delete: operationId: deleteTask description: Soft-delete this task from lists and lookups. To stop running work, call cancel before deleting. Requires `agents:manage`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "204": description: No response body headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Delete Legacy Agent Task x-mint: metadata: sidebarTitle: Legacy Agent Task - Delete /agents/browser-use/{agentId}/tasks/{id}/cancel/: post: operationId: cancelTask description: "Cancel Legacy Agent Task: POST /agents/browser-use/{agentId}/tasks/{id}/cancel/. See the Developer guides for workflow examples and error recovery." parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelTaskResponse" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": content: application/json: schema: $ref: "#/components/schemas/CancelTaskConflictResponse" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Cancel Legacy Agent Task x-mint: metadata: sidebarTitle: Legacy Agent Task - Cancel /agents/browser-use/{agentId}/tasks/{id}/result/: get: operationId: getTaskResult description: Read task status and its result. Pending work returns a message; completed work returns result (which may be null); failed work may include error_message. The HTTP status is 200 even while work is unfinished. Requires `agents:read`. parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/BrowserTaskResult" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Legacy Agent Task Result x-mint: metadata: sidebarTitle: Legacy Agent Task Result - Get /agents/browser-use/{id}/: get: operationId: getAgent description: Retrieve one resource visible to this API key. Inaccessible resources return 404. Requires `agents:read`. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this browser use agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Legacy Browser-Use Agent x-mint: metadata: sidebarTitle: Legacy Browser-Use Agent - Get put: operationId: updateAgent description: Update the supplied writable fields. Omitted optional fields retain their values; this does not reset the resource to defaults. Requires `agents:manage`. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this browser use agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/AgentDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/AgentDetail" multipart/form-data: schema: $ref: "#/components/schemas/AgentDetail" required: true security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Update Legacy Browser-Use Agent x-mint: metadata: sidebarTitle: Legacy Browser-Use Agent - Update patch: operationId: updateAgentStatusPartial description: Update only supplied writable fields. Read-only and unknown fields are ignored by the model serializer. Requires `agents:manage`. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this browser use agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agents API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedAgentDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedAgentDetail" multipart/form-data: schema: $ref: "#/components/schemas/PatchedAgentDetail" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/AgentDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Patch Legacy Browser-Use Agent x-mint: metadata: sidebarTitle: Legacy Browser-Use Agent - Patch delete: operationId: deleteAgent description: Permanently delete a standalone browser profile and its browser tasks. A profile backing a persistent agent returns 409 (browser_profile_in_use); use DELETE /agents/{id}/ to archive that agent instead. Archived and inaccessible profiles return 404. Requires `agents:manage`. parameters: - in: path name: id schema: type: string format: uuid description: A UUID string identifying this browser use agent. required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "204": description: No response body headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": content: application/json: schema: $ref: "#/components/schemas/BrowserProfileDeletionConflict" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Delete Legacy Browser-Use Agent x-mint: metadata: sidebarTitle: Legacy Browser-Use Agent - Delete /operations/{operationId}/: get: operationId: getOperationOutcome parameters: - in: path name: operationId schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Operation outcomes security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/OperationOutcome" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Retrieve safe retained operation metadata for the original credential owner. Requires read scope plus current original-operation scope and resource authority. No stored response bodies or secrets are returned. Covered G02 member and allowed G01 service receipts only; expired/inaccessible records return 404. Requires `agents:read`. x-required-api-key-scope: agents:read x-service-credential-access: supported: true requiredScope: agents:read requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Operation Outcome /ping/: get: operationId: ping description: Test API connectivity with a simple ping endpoint Requires `agents:read`. tags: - Utilities security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PingResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false summary: Ping API /security/interventions: post: operationId: createSecurityIntervention description: Requires security:halt on a scoped service identity. Strict JSON, maximum 16 KiB. Deduplicates by service identity and external_event_id for the Organization lifetime. Acceptance does not prove execution stopped. tags: - Security interventions requestBody: content: application/json: schema: type: object additionalProperties: false required: - external_event_id - target - action - reason properties: external_event_id: type: string minLength: 1 maxLength: 160 description: NFC-normalized and trimmed before validation and identity-scoped deduplication. target: type: object required: - type - id properties: type: type: string enum: - agent id: type: string format: uuid additionalProperties: false action: type: string enum: - halt reason: type: string minLength: 1 maxLength: 1000 description: NFC-normalized and trimmed. Stored as external text, never passed to the agent/model. incident_reference: type: string nullable: true maxLength: 255 description: NFC-normalized and trimmed; omitted, null or blank values become an empty response string. security: - SecurityServiceBearer: [] responses: "200": headers: Cache-Control: schema: type: string enum: - no-store description: Successful security responses must not be cached. required: true Location: schema: type: string format: uri-reference description: Relative URL equal to the response body's status_url. required: true X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. content: application/json: schema: type: object required: - id - target - action - state - hold_active - replayed - external_event_id - reason - incident_reference - status_url - control_state_url - enforcement - enforcing_at - enforced_at - failed_at - released_at - accepted_at - updated_at - state_updated_at properties: id: type: string format: uuid target: type: object required: - type - id properties: type: type: string enum: - agent id: type: string format: uuid additionalProperties: false action: type: string enum: - halt state: type: string enum: - accepted - enforcing - enforced - partially_enforced - failed - released description: Lifecycle of this intervention; separate from hold_active and effective agent state. hold_active: type: boolean description: Whether this intervention still authorizes a hold, including when enforcement has failed. replayed: type: boolean description: True only for an identical POST retry. GET reads return false. enum: - true external_event_id: type: string reason: type: string incident_reference: type: string status_url: type: string format: uri-reference description: Relative intervention status URL on the same deployment; no trailing slash. control_state_url: type: string format: uri-reference description: Relative URL for the agent's effective state across all holds; no trailing slash. enforcement: type: object required: - admission_barrier - dispatch_barrier - worker_acknowledgement - known_work properties: admission_barrier: type: string enum: - active - inactive description: This intervention's admission hold; another intervention may still hold the agent after this one is released. dispatch_barrier: type: string enum: - active - inactive description: This intervention's dispatch hold. Use control_state_url for effective agent-wide barriers. worker_acknowledgement: type: string enum: - pending - acknowledged - failed description: "Shared DT runtime cleanup only: acknowledged does not certify other required cleanup or provider cancellation; pending is not proof of process absence." known_work: type: object required: - pending - cancellation_requested - cancelled - terminal - unknown - failed properties: pending: type: integer minimum: 0 description: Tracked work awaiting a settled outcome. cancellation_requested: type: integer minimum: 0 description: Tracked work with cancellation requested but not confirmed. cancelled: type: integer minimum: 0 description: Tracked work recorded as cancelled. terminal: type: integer minimum: 0 description: Tracked work with a known terminal outcome. unknown: type: integer minimum: 0 description: Tracked work whose external outcome is unknown; local termination does not prove provider cancellation. failed: type: integer minimum: 0 description: Unresolved tracked work recorded as failed; can keep lifecycle partially_enforced after required cleanup is verified. description: Work tracked by this intervention; overlapping interventions can reference the same work. enforcing_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. enforced_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. failed_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. released_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. accepted_at: type: string format: date-time updated_at: type: string format: date-time description: Last intervention row update. state_updated_at: type: string format: date-time description: Currently mirrors updated_at; not an independent lifecycle-transition clock. description: Identical identity/event retry; original intervention's current state, including released state. "202": headers: Cache-Control: schema: type: string enum: - no-store description: Successful security responses must not be cached. required: true Location: schema: type: string format: uri-reference description: Relative URL equal to the response body's status_url. required: true X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. content: application/json: schema: type: object required: - id - target - action - state - hold_active - replayed - external_event_id - reason - incident_reference - status_url - control_state_url - enforcement - enforcing_at - enforced_at - failed_at - released_at - accepted_at - updated_at - state_updated_at properties: id: type: string format: uuid target: type: object required: - type - id properties: type: type: string enum: - agent id: type: string format: uuid additionalProperties: false action: type: string enum: - halt state: type: string enum: - accepted - enforcing - enforced - partially_enforced - failed - released description: Lifecycle of this intervention; separate from hold_active and effective agent state. hold_active: type: boolean description: Whether this intervention still authorizes a hold, including when enforcement has failed. replayed: type: boolean description: True only for an identical POST retry. GET reads return false. enum: - false external_event_id: type: string reason: type: string incident_reference: type: string status_url: type: string format: uri-reference description: Relative intervention status URL on the same deployment; no trailing slash. control_state_url: type: string format: uri-reference description: Relative URL for the agent's effective state across all holds; no trailing slash. enforcement: type: object required: - admission_barrier - dispatch_barrier - worker_acknowledgement - known_work properties: admission_barrier: type: string enum: - active - inactive description: This intervention's admission hold; another intervention may still hold the agent after this one is released. dispatch_barrier: type: string enum: - active - inactive description: This intervention's dispatch hold. Use control_state_url for effective agent-wide barriers. worker_acknowledgement: type: string enum: - pending - acknowledged - failed description: "Shared DT runtime cleanup only: acknowledged does not certify other required cleanup or provider cancellation; pending is not proof of process absence." known_work: type: object required: - pending - cancellation_requested - cancelled - terminal - unknown - failed properties: pending: type: integer minimum: 0 description: Tracked work awaiting a settled outcome. cancellation_requested: type: integer minimum: 0 description: Tracked work with cancellation requested but not confirmed. cancelled: type: integer minimum: 0 description: Tracked work recorded as cancelled. terminal: type: integer minimum: 0 description: Tracked work with a known terminal outcome. unknown: type: integer minimum: 0 description: Tracked work whose external outcome is unknown; local termination does not prove provider cancellation. failed: type: integer minimum: 0 description: Unresolved tracked work recorded as failed; can keep lifecycle partially_enforced after required cleanup is verified. description: Work tracked by this intervention; overlapping interventions can reference the same work. enforcing_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. enforced_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. failed_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. released_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. accepted_at: type: string format: date-time updated_at: type: string format: date-time description: Last intervention row update. state_updated_at: type: string format: date-time description: Currently mirrors updated_at; not an independent lifecycle-transition clock. description: Intervention, barrier, and evidence committed. Acceptance is not termination proof. "400": content: application/json: schema: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: "invalid_request, unsupported_target_type, or unsupported_action: invalid JSON/fields/limits or unsupported target/action." headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "401": headers: WWW-Authenticate: schema: type: string enum: - Bearer realm="security-interventions" description: Present on authentication failures; a POST rejected by the locked credential recheck has no challenge. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. content: application/json: schema: oneOf: - type: object required: - detail properties: detail: type: string - type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: Authentication failures use detail and a Bearer challenge. If credentials become unavailable before the locked acceptance check, invalid_security_service_credential uses error/message without a challenge. "403": content: application/json: schema: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: "security_permission_denied: missing required security permission." headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "404": content: application/json: schema: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: "target_not_found: Unknown, wrong-Organization, or out-of-scope target; indistinguishable to the caller." headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "409": content: application/json: schema: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: external_event_id_conflict for changed event semantics; agent_emergency_unavailable if the isolated runtime is disabled; agent_emergency_owner_changed for an ownership conflict. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "413": content: application/json: schema: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: "request_too_large: request body exceeds 16 KiB." headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "500": content: application/json: schema: type: object required: - detail - error_id properties: detail: type: string error_id: type: string format: uuid description: Unexpected server failure. Retain error_id for support; do not assume a timed-out or failed create was never accepted. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. x-required-security-service-permission: security:halt /security/interventions/{interventionId}: get: operationId: getSecurityIntervention description: Requires security:read and current explicit agent scope. Reads durable control/work evidence independently of the normal execution queue. parameters: - in: path name: interventionId schema: type: string format: uuid required: true tags: - Security interventions security: - SecurityServiceBearer: [] responses: "200": headers: Cache-Control: schema: type: string enum: - no-store description: Successful security responses must not be cached. required: true X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. content: application/json: schema: type: object required: - id - target - action - state - hold_active - replayed - external_event_id - reason - incident_reference - status_url - control_state_url - enforcement - enforcing_at - enforced_at - failed_at - released_at - accepted_at - updated_at - state_updated_at properties: id: type: string format: uuid target: type: object required: - type - id properties: type: type: string enum: - agent id: type: string format: uuid additionalProperties: false action: type: string enum: - halt state: type: string enum: - accepted - enforcing - enforced - partially_enforced - failed - released description: Lifecycle of this intervention; separate from hold_active and effective agent state. hold_active: type: boolean description: Whether this intervention still authorizes a hold, including when enforcement has failed. replayed: type: boolean description: True only for an identical POST retry. GET reads return false. enum: - false external_event_id: type: string reason: type: string incident_reference: type: string status_url: type: string format: uri-reference description: Relative intervention status URL on the same deployment; no trailing slash. control_state_url: type: string format: uri-reference description: Relative URL for the agent's effective state across all holds; no trailing slash. enforcement: type: object required: - admission_barrier - dispatch_barrier - worker_acknowledgement - known_work properties: admission_barrier: type: string enum: - active - inactive description: This intervention's admission hold; another intervention may still hold the agent after this one is released. dispatch_barrier: type: string enum: - active - inactive description: This intervention's dispatch hold. Use control_state_url for effective agent-wide barriers. worker_acknowledgement: type: string enum: - pending - acknowledged - failed description: "Shared DT runtime cleanup only: acknowledged does not certify other required cleanup or provider cancellation; pending is not proof of process absence." known_work: type: object required: - pending - cancellation_requested - cancelled - terminal - unknown - failed properties: pending: type: integer minimum: 0 description: Tracked work awaiting a settled outcome. cancellation_requested: type: integer minimum: 0 description: Tracked work with cancellation requested but not confirmed. cancelled: type: integer minimum: 0 description: Tracked work recorded as cancelled. terminal: type: integer minimum: 0 description: Tracked work with a known terminal outcome. unknown: type: integer minimum: 0 description: Tracked work whose external outcome is unknown; local termination does not prove provider cancellation. failed: type: integer minimum: 0 description: Unresolved tracked work recorded as failed; can keep lifecycle partially_enforced after required cleanup is verified. description: Work tracked by this intervention; overlapping interventions can reference the same work. enforcing_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. enforced_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. failed_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. released_at: type: string format: date-time nullable: true description: Transition time, or null if that transition has not occurred. accepted_at: type: string format: date-time updated_at: type: string format: date-time description: Last intervention row update. state_updated_at: type: string format: date-time description: Currently mirrors updated_at; not an independent lifecycle-transition clock. description: Current intervention state and work evidence; another active hold may still apply. "401": headers: WWW-Authenticate: schema: type: string enum: - Bearer realm="security-interventions" description: Present on authentication failures; a POST rejected by the locked credential recheck has no challenge. required: true X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. content: application/json: schema: type: object required: - detail properties: detail: type: string description: Missing, invalid, disabled, revoked, or unavailable service credential; HTTPS is required by default. Includes the Bearer authentication challenge. "403": content: application/json: schema: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: "security_permission_denied: missing required security permission." headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "404": content: application/json: schema: type: object required: - detail properties: detail: type: string description: Unknown, wrong-Organization, or out-of-scope target; indistinguishable to the caller. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "500": content: application/json: schema: type: object required: - detail - error_id properties: detail: type: string error_id: type: string format: uuid description: Unexpected server failure. Retain error_id for support; do not assume a timed-out or failed create was never accepted. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. x-required-security-service-permission: security:read /security/targets/agent/{agentId}/control-state: get: operationId: getSecurityTargetControlState description: Requires security:read and current explicit agent scope. Effective hold, barrier, worker acknowledgement and unknown external work are separate facts. parameters: - in: path name: agentId schema: type: string format: uuid required: true tags: - Security interventions security: - SecurityServiceBearer: [] responses: "200": headers: Cache-Control: schema: type: string enum: - no-store description: Successful security responses must not be cached. required: true X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. content: application/json: schema: type: object required: - target - held - effective_state - active_intervention_ids - generation - as_of - barriers - workers - in_flight properties: target: type: object required: - type - id properties: type: type: string enum: - agent id: type: string format: uuid additionalProperties: false held: type: boolean description: Effective hold across all active interventions and any existing emergency latch. effective_state: type: string enum: - active - accepted - enforcing - enforced - partially_enforced - failed description: Aggregate active-hold state. active means no hold remains, not that unresolved external work has been undone. active_intervention_ids: type: array items: type: string format: uuid description: All active holds on the scoped agent, including internal and other service identities' interventions. generation: type: integer minimum: 0 as_of: type: string format: date-time description: Time of the coherent durable control-state snapshot. barriers: type: object required: - admission - dispatch properties: admission: type: string enum: - active - inactive dispatch: type: string enum: - active - inactive workers: type: object required: - acknowledged - status properties: acknowledged: type: boolean description: True when shared runtime cleanup is verified. status: type: string enum: - not_applicable - pending - verified - failed description: Runtime cleanup status; not_applicable also applies when no emergency control exists. in_flight: type: object required: - known - cancellation_requested - cancelled - terminal - unknown - failed properties: known: type: integer minimum: 0 description: Tracked work awaiting a settled outcome. cancellation_requested: type: integer minimum: 0 description: Tracked work with cancellation requested but not confirmed. cancelled: type: integer minimum: 0 description: Tracked work recorded as cancelled. terminal: type: integer minimum: 0 description: Tracked work with a known terminal outcome. unknown: type: integer minimum: 0 description: Tracked work whose external outcome is unknown; local termination does not prove provider cancellation. failed: type: integer minimum: 0 description: Unresolved tracked work recorded as failed; can keep lifecycle partially_enforced after required cleanup is verified. description: Evidence inventory, not a running-process count. Shared work is counted once; active holds include settled work, while released holds contribute only unresolved evidence. description: Effective agent hold, shared barriers and runtime acknowledgement, and deduplicated work counts. "401": headers: WWW-Authenticate: schema: type: string enum: - Bearer realm="security-interventions" description: Present on authentication failures; a POST rejected by the locked credential recheck has no challenge. required: true X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. content: application/json: schema: type: object required: - detail properties: detail: type: string description: Missing, invalid, disabled, revoked, or unavailable service credential; HTTPS is required by default. Includes the Bearer authentication challenge. "403": content: application/json: schema: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: "security_permission_denied: missing required security permission." headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "404": content: application/json: schema: oneOf: - type: object required: - detail properties: detail: type: string - type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. message: type: string description: Human-readable explanation. description: Unknown, wrong-Organization, or out-of-scope target; indistinguishable to the caller. A concurrent target ownership change uses error/message with target_not_found; ordinary missing lookups use detail. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. "500": content: application/json: schema: type: object required: - detail - error_id properties: detail: type: string error_id: type: string format: uuid description: Unexpected server failure. Retain error_id for support; do not assume a timed-out or failed create was never accepted. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; distinct from protocol/resource identities. x-required-security-service-permission: security:read /setup/workspaces/: get: operationId: listSetupWorkspaces parameters: - in: query name: page schema: type: integer - in: query name: page_size schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - Agent setup security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/MetadataResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" description: Requires `agents:read`. Deterministic stored configuration only; no worker/network/provider reachability evidence. New mutations require API_CONFIGURATION_ENABLED, Idempotency-Key and (except schedule creation) an exact If-Match ETag. Current authority precedes retained replay; matching replay returns the original outcome before testing its historical conditional revision. Disable/delete do not cancel an admitted occurrence. Setup controls require a member-issued key; service credentials may only use explicitly granted named schedules. x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field /tasks/browser-use/: get: operationId: listAllTasks description: List browser tasks visible to this key, including tasks without a browser agent. Returns a paginated results envelope. Requires `agents:read`. parameters: - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - name: page_size required: false in: query description: Number of results to return per page. schema: type: integer - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaginatedTaskListList" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: List Standalone Legacy Tasks x-mint: metadata: sidebarTitle: Standalone Legacy Tasks - List post: operationId: assignTask2 description: Create a resource in the API key's owner scope. Read-only fields in the representation cannot be set by the client. Requires `agents:operate`. When API_ADMISSION_ENABLED is true, omit wait even without Idempotency-Key; queued-input capacity is shared across stable principal and owner. Optional protected retries require API_EXTENDED_RETRIES_ENABLED for new admissions; retained retries survive disabling admission. Original outcomes expire after 24 hours by default; current authority is rechecked. Task creation requires wait to be omitted. Secret rotation retries conflict if superseded. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/TaskDetail" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/TaskDetail" multipart/form-data: schema: $ref: "#/components/schemas/TaskDetail" security: - ApiKeyAuth: [] responses: "201": content: application/json: schema: $ref: "#/components/schemas/TaskCreateResponse" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. Operation-Id: schema: type: string format: uuid description: Opaque retained receipt ID. Outcome lookup is available for covered G02 member and allowed G01 service operations. Idempotency-Expires-At: schema: type: string format: date-time description: Original protected response expiry. Idempotency-Replayed: schema: type: string enum: - "true" - "false" description: "Present when Idempotency-Key is used: false for the original response, true for a replay." X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "402": content: application/json: schema: $ref: "#/components/schemas/InsufficientCreditsResponse" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": description: Idempotency key reused for a different request, or an incompatible resource state. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. task_secrets_unavailable: credential encryption is unavailable; no task secret/input changes were committed. This error has no Retry-After readiness interval." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: true concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false requiresAsyncSubmissionWhenEnabled: true parameters: - in: header name: Idempotency-Key required: false schema: type: string minLength: 1 maxLength: 255 description: API-key-scoped retry key. Reuse with the same method, path, and JSON body; completed responses are retained for 24 hours by default. - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Create Standalone Legacy Task x-mint: metadata: sidebarTitle: Standalone Legacy Task - Create /tasks/browser-use/{id}/: get: operationId: getTask2 description: Retrieve one resource visible to this API key. Inaccessible resources return 404. Requires `agents:read`. parameters: - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Standalone Legacy Task x-mint: metadata: sidebarTitle: Standalone Legacy Task - Get put: operationId: updateTask2 description: Update supplied writable task inputs while pending and unclaimed. A supplied secrets map replaces all task credentials; {} clears them, omission preserves them, and null is invalid. Secret columns and other inputs commit atomically. A winning worker claim or cancellation rejects input edits with 400; deleted or retention-purged tasks return 404. Webhook-only edits remain available on retained running/terminal tasks. Responses never return credentials or key lists. Success acknowledges stored input, not execution or authentication. These updates have no credential readback, conditional revision or idempotency guarantee. Requires `agents:operate`. parameters: - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/TaskUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/TaskUpdate" multipart/form-data: schema: $ref: "#/components/schemas/TaskUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. task_secrets_unavailable: credential encryption is unavailable; no task secret/input changes were committed. This error has no Retry-After readiness interval." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Update Standalone Legacy Task x-mint: metadata: sidebarTitle: Standalone Legacy Task - Update patch: operationId: updateTaskStatusPartial2 description: Update supplied writable task inputs while pending and unclaimed. A supplied secrets map replaces all task credentials; {} clears them, omission preserves them, and null is invalid. Secret columns and other inputs commit atomically. A winning worker claim or cancellation rejects input edits with 400; deleted or retention-purged tasks return 404. Webhook-only edits remain available on retained running/terminal tasks. Responses never return credentials or key lists. Success acknowledges stored input, not execution or authentication. These updates have no credential readback, conditional revision or idempotency guarantee. Requires `agents:operate`. parameters: - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API requestBody: content: application/json: schema: $ref: "#/components/schemas/PatchedTaskUpdate" application/x-www-form-urlencoded: schema: $ref: "#/components/schemas/PatchedTaskUpdate" multipart/form-data: schema: $ref: "#/components/schemas/PatchedTaskUpdate" security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/TaskDetail" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: "admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. task_secrets_unavailable: credential encryption is unavailable; no task secret/input changes were committed. This error has no Retry-After readiness interval." content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: true unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Patch Standalone Legacy Task x-mint: metadata: sidebarTitle: Standalone Legacy Task - Patch delete: operationId: deleteTask2 description: Soft-delete this task from lists and lookups. To stop running work, call cancel before deleting. Requires `agents:manage`. parameters: - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "204": description: No response body headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:manage x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Delete Standalone Legacy Task x-mint: metadata: sidebarTitle: Standalone Legacy Task - Delete /tasks/browser-use/{id}/cancel/: post: operationId: cancelTask2 description: "Cancel Standalone Legacy Task: POST /tasks/browser-use/{id}/cancel/. See the Developer guides for workflow examples and error recovery." parameters: - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelTaskResponse" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "409": content: application/json: schema: $ref: "#/components/schemas/CancelTaskConflictResponse" description: "" headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:operate x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: false queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Cancel Standalone Legacy Task x-mint: metadata: sidebarTitle: Standalone Legacy Task - Cancel /tasks/browser-use/{id}/result/: get: operationId: getTaskResult2 description: Read task status and its result. Pending work returns a message; completed work returns result (which may be null); failed work may include error_message. The HTTP status is 200 even while work is unfinished. Requires `agents:read`. parameters: - in: path name: id schema: type: string format: uuid required: true - in: header name: X-API-Contract required: false schema: type: string enum: - "2026-10-14" description: Opt in to coded errors and covered strict configuration inputs; omission preserves legacy behavior. - in: header name: X-Client-Correlation-ID required: false schema: type: string format: uuid maxLength: 36 description: Canonical caller UUID, echoed only when valid; distinct from generated X-Request-ID. tags: - browser-use Tasks API security: - ApiKeyAuth: [] responses: "200": content: application/json: schema: $ref: "#/components/schemas/BrowserTaskResult" description: "" headers: RateLimit-Limit: schema: type: string description: Smaller configured principal/owner request window limit when enforcement is enabled. RateLimit-Remaining: schema: type: string description: Smaller remaining principal/owner allowance at admission. RateLimit-Reset: schema: type: string description: Seconds until the Redis-server-time fixed request window resets. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. "400": description: Invalid request body or query parameters. Field errors may be returned as arrays. content: application/json: schema: anyOf: - type: object additionalProperties: true - type: array items: {} description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "403": description: Missing/invalid API key, insufficient scope, account eligibility, or communication policy denial. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "404": description: Resource not found or not accessible to this API key. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "429": description: request_quota_exceeded or wait_capacity_exceeded. Honor Retry-After; no new input was accepted. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "500": description: Unexpected failure; JSON includes detail and an error_id for support. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" "503": description: admission_unavailable or work_capacity_exceeded. Honor Retry-After and preserve protected-write keys. content: application/json: schema: type: object additionalProperties: true description: Error details vary by failure. See the Errors and recovery guide for field errors, scope errors, and state conflicts. headers: Retry-After: schema: type: string description: Seconds until the suggested retry, not a readiness guarantee. X-Request-ID: schema: type: string format: uuid description: Server-generated synchronous HTTP correlation; no worker lineage implied. x-versioned-error-schema: $ref: "#/components/schemas/VersionedRestError" x-required-api-key-scope: agents:read x-service-credential-access: supported: false requiredScope: null requiresInstallationAndOrganizationEnablement: true idempotencySupported: false x-api-admission: requiresDeploymentEnablement: true requestQuota: true queuedInputCapacity: false concurrentWaitCapacity: false namespaces: - member-user-or-service-identity - effective-owner acceptedReplayUsesNewWorkCapacity: false x-api-contract: version: "2026-10-14" errorSchema: $ref: "#/components/schemas/VersionedRestError" strictInputs: false unknownFieldCode: unknown_field readOnlyFieldCode: read_only_field summary: Get Standalone Legacy Task Result x-mint: metadata: sidebarTitle: Standalone Legacy Task Result - Get components: schemas: AgentActivationResponse: type: object properties: status: $ref: "#/components/schemas/AgentActivationStatus" updated: type: boolean required: - status - updated AgentActivationStatus: enum: - activated - deactivated type: string description: |- * `activated` - activated * `deactivated` - deactivated AgentContact: type: object properties: id: type: string format: uuid readOnly: true agent_id: type: string format: uuid readOnly: true channel: allOf: - $ref: "#/components/schemas/CommunicationChannel" readOnly: true address: type: string readOnly: true description: Email address or E.164 phone number is_active: type: boolean readOnly: true verified: type: boolean readOnly: true description: Reserved for future use. Manual verification flag; currently not enforced. allow_inbound: type: boolean readOnly: true description: Whether this contact can send messages to the agent allow_outbound: type: boolean readOnly: true description: Whether the agent can send messages to this contact can_configure: type: boolean readOnly: true description: Whether this contact can instruct the agent to update its charter or schedule created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true AgentContactCreate: type: object properties: channel: $ref: "#/components/schemas/ContactChannel" address: type: string maxLength: 512 allow_inbound: type: boolean default: true allow_outbound: type: boolean default: true can_configure: type: boolean default: false required: - address - channel AgentContactEndpoint: type: object properties: id: type: string format: uuid owner_agent_id: type: string format: uuid nullable: true channel: $ref: "#/components/schemas/CommunicationChannel" address: type: string is_primary: type: boolean is_preferred: type: boolean safe_for_preferred_contact: type: boolean required: - address - channel - id - is_preferred - is_primary - owner_agent_id - safe_for_preferred_contact AgentContactEndpointListResponse: type: object properties: endpoints: type: array items: $ref: "#/components/schemas/AgentContactEndpoint" preferred_contact_endpoint_id: type: string format: uuid nullable: true required: - endpoints - preferred_contact_endpoint_id AgentContactListResponse: type: object properties: contacts: type: array items: $ref: "#/components/schemas/AgentContact" count: type: integer minimum: 0 required: - contacts - count AgentContactMutationResponse: type: object properties: contact: $ref: "#/components/schemas/AgentContact" created: type: boolean reactivated: type: boolean deactivated: type: boolean required: - contact AgentDetail: type: object properties: id: type: string format: uuid readOnly: true user_email: type: string format: email title: Email address readOnly: true name: type: string maxLength: 255 created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true listing_description: type: string readOnly: true listing_description_source: type: string readOnly: true mini_description: type: string readOnly: true mini_description_source: type: string readOnly: true required: - name AgentFile: type: object properties: file_id: type: string format: uuid name: type: string parent_id: type: string format: uuid nullable: true path: type: string available: type: boolean availability: $ref: "#/components/schemas/AgentFileAvailabilityEnum" scan_status: type: string active_generation: allOf: - $ref: "#/components/schemas/FileGeneration" nullable: true pending_generation: allOf: - $ref: "#/components/schemas/FileGeneration" nullable: true size_bytes: type: integer nullable: true sha256: type: string nullable: true content_type: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - active_generation - availability - available - content_type - created_at - file_id - name - parent_id - path - pending_generation - scan_status - sha256 - size_bytes - updated_at AgentFileAvailabilityEnum: enum: - available - pending - infected - failed - unavailable - purged type: string description: |- * `available` - available * `pending` - pending * `infected` - infected * `failed` - failed * `unavailable` - unavailable * `purged` - purged AgentFilePage: type: object properties: results: type: array items: $ref: "#/components/schemas/AgentFile" next_cursor: type: string nullable: true required: - next_cursor - results AgentInboundWebhook: type: object properties: id: type: string format: uuid name: type: string is_active: type: boolean last_triggered_at: type: string format: date-time nullable: true url: type: string format: uri required: - id - is_active - last_triggered_at - name AgentInboundWebhookCreate: type: object properties: name: type: string maxLength: 128 is_active: type: boolean default: true required: - name AgentInboundWebhookDeleteResponse: type: object properties: deleted_webhook: $ref: "#/components/schemas/AgentInboundWebhook" required: - deleted_webhook AgentInboundWebhookListResponse: type: object properties: webhooks: type: array items: $ref: "#/components/schemas/AgentInboundWebhook" required: - webhooks AgentInboundWebhookResponse: type: object properties: message: type: string webhook: $ref: "#/components/schemas/AgentInboundWebhook" required: - webhook AgentList: type: object properties: id: type: string format: uuid readOnly: true name: type: string maxLength: 255 created_at: type: string format: date-time readOnly: true listing_description: type: string readOnly: true listing_description_source: type: string readOnly: true mini_description: type: string readOnly: true mini_description_source: type: string readOnly: true required: - name AgentMessageResponse: type: object properties: event: $ref: "#/components/schemas/AgentTimelineEvent" required: - event AgentTimelineEvent: type: object properties: kind: type: string description: "Event discriminator: message, steps, thinking, plan, or user_action. Handle additional kinds defensively." cursor: type: string description: Opaque durable cursor. Store and return it unchanged. timestamp: type: string format: date-time description: Steps clusters use earliestTimestamp/latestTimestamp instead. message: type: object additionalProperties: {} description: Message payload with id, bodyText, bodyHtml, channel, isOutbound, inReplyToMessageId, and attachments. See Timeline and events for nested fields. entries: type: array items: type: object additionalProperties: {} entryCount: type: integer earliestTimestamp: type: string format: date-time latestTimestamp: type: string format: date-time collapsible: type: boolean collapseThreshold: type: integer reasoning: type: string completionId: type: string format: uuid snapshot: type: object additionalProperties: {} changes: type: array items: type: object additionalProperties: {} displayText: type: string action: type: object additionalProperties: {} required: - cursor - kind AgentTimelineResponse: type: object properties: events: type: array items: $ref: "#/components/schemas/AgentTimelineEvent" oldest_cursor: type: string nullable: true newest_cursor: type: string nullable: true has_more_older: type: boolean has_more_newer: type: boolean processing_active: type: boolean processing_snapshot: $ref: "#/components/schemas/PersistentAgentProcessingSnapshot" required: - events - has_more_newer - has_more_older - newest_cursor - oldest_cursor - processing_active - processing_snapshot AgentWebTasksResponse: type: object properties: results: type: array items: $ref: "#/components/schemas/TaskList" limit: type: integer maximum: 200 minimum: 0 required: - limit - results AgentWebhook: type: object properties: id: type: string format: uuid name: type: string configuration_revision: type: integer readOnly: true request_visibility: $ref: "#/components/schemas/RequestVisibilityEnum" request_filter: type: string format: uuid nullable: true event_types: type: array items: $ref: "#/components/schemas/WebhookEventType" signature_header: type: string signature_scheme: type: string last_triggered_at: type: string format: date-time nullable: true last_response_status: type: integer nullable: true url: type: string format: uri signing_secret: type: string last_error_message: type: string required: - event_types - id - last_response_status - last_triggered_at - name - signature_header - signature_scheme AgentWebhookCreate: type: object properties: name: type: string maxLength: 128 url: type: string format: uri maxLength: 1024 configuration_revision: type: integer readOnly: true request_visibility: $ref: "#/components/schemas/RequestVisibilityEnum" request_filter: type: string format: uuid nullable: true event_types: type: array items: $ref: "#/components/schemas/WebhookEventType" required: - name - url AgentWebhookDeleteResponse: type: object properties: deleted_webhook: $ref: "#/components/schemas/AgentWebhook" required: - deleted_webhook AgentWebhookListResponse: type: object properties: webhooks: type: array items: $ref: "#/components/schemas/AgentWebhook" required: - webhooks AgentWebhookResponse: type: object properties: message: type: string webhook: $ref: "#/components/schemas/AgentWebhook" required: - webhook ApplicationRequest: type: object properties: request_id: type: string format: uuid message_id: type: string format: uuid nullable: true conversation_id: type: string format: uuid nullable: true client_reference: type: string revision: type: integer result: allOf: - $ref: "#/components/schemas/ApplicationResultMetadata" description: Metadata only; retrieve native value through urls.result. publication_state: $ref: "#/components/schemas/PublicationStateEnum" execution_state: $ref: "#/components/schemas/ExecutionStateEnum" response_state: $ref: "#/components/schemas/ResponseStateEnum" blocked_reason: type: string failure_code: type: string content_purged: type: boolean body: type: string nullable: true input_attachments: type: array items: type: object additionalProperties: {} description: At most ten retained immutable input copies; includes IDs usable by the attachment download route. admitted_at: type: string format: date-time observed_at: type: string format: date-time executions: type: array items: type: object additionalProperties: {} executions_truncated: type: boolean pending_actions: type: array items: type: object additionalProperties: {} pending_actions_truncated: type: boolean continuations: type: array items: type: object additionalProperties: {} continuations_truncated: type: boolean urls: type: object additionalProperties: type: string cursor: type: string receipt_expires_at: type: string format: date-time nullable: true required: - admitted_at - blocked_reason - body - client_reference - content_purged - continuations - continuations_truncated - conversation_id - cursor - execution_state - executions - executions_truncated - failure_code - message_id - observed_at - pending_actions - pending_actions_truncated - publication_state - receipt_expires_at - request_id - response_state - result - revision - urls ApplicationRequestInput: type: object properties: result_schema: description: Optional application-result-v1 restricted Draft 2020-12 schema; 16 KiB, depth 8, 256 nodes. No refs/regex/combinators. body: type: string description: Nonblank input, at most 64 KiB in UTF-8. maxLength: 65536 client_reference: type: string default: "" maxLength: 255 conversation_id: type: string format: uuid attachment_file_ids: type: array items: type: string format: uuid maxItems: 10 required: - body additionalProperties: false ApplicationRequestPage: type: object properties: results: type: array items: $ref: "#/components/schemas/ApplicationRequest" next_cursor: type: string nullable: true required: - next_cursor - results ApplicationRequestWait: type: object properties: cursor: type: string maxLength: 2048 timeout_seconds: type: integer maximum: 30 minimum: 0 default: 30 additionalProperties: false ApplicationResponse: type: object properties: message_id: type: string format: uuid request_ids: type: array items: type: string format: uuid body: type: string nullable: true content_purged: type: boolean created_at: type: string format: date-time attachments: type: array items: type: object additionalProperties: {} required: - attachments - body - content_purged - created_at - message_id - request_ids ApplicationResponsePage: type: object properties: results: type: array items: $ref: "#/components/schemas/ApplicationResponse" next_cursor: type: string nullable: true required: - next_cursor - results ApplicationResult: type: object properties: availability: $ref: "#/components/schemas/ApplicationResultAvailabilityEnum" has_value: type: boolean value: nullable: true result: $ref: "#/components/schemas/ApplicationResultMetadata" required: - availability - has_value - result ApplicationResultAvailabilityEnum: enum: - available - purged - unavailable type: string description: |- * `available` - available * `purged` - purged * `unavailable` - unavailable ApplicationResultMetadata: type: object properties: state: $ref: "#/components/schemas/StateEnum" error_code: type: string schema_hash: type: string nullable: true profile: type: string nullable: true artifact_id: type: string format: uuid nullable: true version: type: integer nullable: true checksum_sha256: type: string nullable: true size_bytes: type: integer nullable: true processing_step_id: type: string format: uuid nullable: true completion_id: type: string format: uuid nullable: true runtime_execution_id: type: string format: uuid nullable: true created_at: type: string format: date-time nullable: true required: - artifact_id - checksum_sha256 - completion_id - created_at - error_code - processing_step_id - profile - runtime_execution_id - schema_hash - size_bytes - state - version ApplicationWaitResult: type: object properties: changed: type: boolean cursor: type: string request: $ref: "#/components/schemas/ApplicationRequest" required: - changed - cursor - request BrowserProfileDeletionConflict: type: object properties: detail: type: string code: type: string required: - code - detail BrowserTaskResult: type: object properties: id: type: string format: uuid agent_id: type: string format: uuid nullable: true status: $ref: "#/components/schemas/BrowserTaskResultStatusEnum" result: nullable: true message: type: string error_message: type: string required: - agent_id - id - status BrowserTaskResultStatusEnum: enum: - pending - in_progress - completed - failed - cancelled type: string description: |- * `pending` - pending * `in_progress` - in_progress * `completed` - completed * `failed` - failed * `cancelled` - cancelled BrowserTaskStatus: enum: - pending - in_progress - completed - failed - cancelled type: string description: |- * `pending` - Pending * `in_progress` - In Progress * `completed` - Completed * `failed` - Failed * `cancelled` - Cancelled CancelTaskConflictResponse: type: object properties: detail: type: string required: - detail CancelTaskResponse: type: object properties: status: type: string message: type: string required: - message - status CommunicationChannel: enum: - email - sms - slack - discord - web - other type: string description: |- * `email` - Email * `sms` - SMS * `slack` - Slack * `discord` - Discord * `web` - Web Chat * `other` - Other ConfigurationResponse: type: object description: Domain-service metadata varies by provider; never includes secret values. properties: configuration_revision: type: string configuration: type: object additionalProperties: {} execution_tested: type: boolean required: - configuration - configuration_revision - execution_tested ContactApprovalModeEnum: enum: - require_approval - auto_approve_email type: string description: |- * `require_approval` - Require approval * `auto_approve_email` - Automatically allow email contacts ContactChannel: enum: - email - web type: string description: |- * `email` - Email * `web` - Web Chat Delivery: type: object properties: id: type: string format: uuid event_id: type: string format: uuid event_type: type: string status: $ref: "#/components/schemas/DeliveryStatusEnum" reason_code: type: string revision: type: integer cycle: type: integer attempt_count: type: integer configuration_revision: type: integer nullable: true created_at: type: string format: date-time next_attempt_at: type: string format: date-time last_attempted_at: type: string format: date-time nullable: true delivered_at: type: string format: date-time nullable: true last_response_status: type: integer nullable: true attempts: type: array items: type: object additionalProperties: {} recoveries: type: array items: type: object additionalProperties: {} recovery: type: object additionalProperties: {} required: - attempt_count - configuration_revision - created_at - cycle - delivered_at - event_id - event_type - id - last_attempted_at - last_response_status - next_attempt_at - reason_code - revision - status DeliveryPage: type: object properties: results: type: array items: $ref: "#/components/schemas/Delivery" next_cursor: type: string nullable: true diagnostics: type: object additionalProperties: {} required: - diagnostics - next_cursor - results DeliveryStatusEnum: enum: - pending - delivering - delivered - failed - cancelled - unknown type: string description: |- * `pending` - pending * `delivering` - delivering * `delivered` - delivered * `failed` - failed * `cancelled` - cancelled * `unknown` - unknown EmailSendingModeEnum: enum: - review_all_external - review_new_contacts - send_automatically type: string description: |- * `review_all_external` - Review before send * `review_new_contacts` - Review only new contacts * `send_automatically` - Send automatically EmptyInput: type: object additionalProperties: false ExecutionStateEnum: enum: - not_started - processing - awaiting_action - blocked - settled - failed - unknown type: string description: |- * `not_started` - not_started * `processing` - processing * `awaiting_action` - awaiting_action * `blocked` - blocked * `settled` - settled * `failed` - failed * `unknown` - unknown FileGeneration: type: object properties: generation_id: type: string format: uuid scan_status: $ref: "#/components/schemas/ScanStatusEnum" sha256: type: string nullable: true size_bytes: type: integer required: - generation_id - scan_status - sha256 - size_bytes FileInput: type: object properties: file: type: string format: binary name: type: string maxLength: 255 parent_id: type: string format: uuid nullable: true required: - file - name FileReplace: type: object properties: file: type: string format: binary required: - file FromActorTypeEnum: enum: - agent - human_user - external - system type: string description: |- * `agent` - agent * `human_user` - human_user * `external` - external * `system` - system InsufficientCreditsResponse: type: object properties: message: type: string required: - message KindEnum: enum: - recurring - once type: string description: |- * `recurring` - Recurring * `once` - One time LifeStateEnum: enum: - active - expired type: string description: |- * `active` - Active * `expired` - Expired MetadataResponse: type: object description: Non-secret metadata varies by provider and published operation schema. properties: status: type: string code: type: string action: type: object additionalProperties: {} context: type: object additionalProperties: {} retry: type: object additionalProperties: {} verification: type: string kind: type: string id: type: string name: type: string integration: type: object additionalProperties: {} integrations: type: array items: type: object additionalProperties: {} binding: type: object additionalProperties: {} nullable: true operations: type: object additionalProperties: {} configuration: type: object additionalProperties: {} capabilities: type: object additionalProperties: {} connection_status: type: string connected: type: boolean credential_id: type: string format: uuid nullable: true requested_scopes: type: array items: type: string enabled_system_skills: type: array items: type: string enabled_tools: type: array items: type: string setup_url: type: string checks: type: array items: type: object additionalProperties: {} configuration_ready: type: boolean nullable: true execution_tested: type: boolean checked_at: type: string format: date-time agent_id: type: string format: uuid teams: type: array items: type: object additionalProperties: {} workspaces: type: array items: type: object additionalProperties: {} private_workspace: type: object additionalProperties: {} page: type: integer page_size: type: integer total: type: integer has_next: type: boolean OperationOutcome: type: object properties: operation_id: type: string format: uuid operation: type: string resources: {} outcome: type: string response_status: type: integer expires_at: type: string format: date-time publication: {} required: - expires_at - operation - operation_id - outcome - resources - response_status PaginatedAgentListList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: "#/components/schemas/AgentList" PaginatedPersistentAgentArchivedListList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: "#/components/schemas/PersistentAgentArchivedList" PaginatedPersistentAgentListList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: "#/components/schemas/PersistentAgentList" PaginatedTaskListList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: "#/components/schemas/TaskList" PatchedAgentConfigurationPatch: type: object properties: name: type: string maxLength: 255 charter: type: string maxLength: 65536 schedule: type: string nullable: true maxLength: 128 proactive_opt_in: type: boolean preferred_llm_tier: type: string maxLength: 64 whitelist_policy: type: string maxLength: 64 contact_approval_mode: type: string maxLength: 64 additionalProperties: false PatchedAgentContactUpdate: type: object properties: is_active: type: boolean allow_inbound: type: boolean allow_outbound: type: boolean can_configure: type: boolean PatchedAgentDetail: type: object properties: id: type: string format: uuid readOnly: true user_email: type: string format: email title: Email address readOnly: true name: type: string maxLength: 255 created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true listing_description: type: string readOnly: true listing_description_source: type: string readOnly: true mini_description: type: string readOnly: true mini_description_source: type: string readOnly: true PatchedAgentInboundWebhookUpdate: type: object properties: name: type: string maxLength: 128 is_active: type: boolean PatchedAgentWebhookUpdate: type: object properties: name: type: string maxLength: 128 url: type: string format: uri maxLength: 1024 configuration_revision: type: integer readOnly: true request_visibility: $ref: "#/components/schemas/RequestVisibilityEnum" request_filter: type: string format: uuid nullable: true event_types: type: array items: $ref: "#/components/schemas/WebhookEventType" PatchedBinding: type: object properties: enabled: type: boolean credential_id: type: string format: uuid nullable: true approver_ids: type: array items: type: integer minimum: 1 maxItems: 100 additionalProperties: false PatchedPeerLinkUpdate: type: object properties: messages_per_window: type: integer maximum: 500 minimum: 1 window_hours: type: integer maximum: 168 minimum: 1 is_enabled: type: boolean additionalProperties: false PatchedPersistentAgentDetail: type: object properties: id: type: string format: uuid readOnly: true name: type: string description: Display name. Required when the organization requires agent names; otherwise a name is generated when omitted. maxLength: 255 charter: type: string short_description: type: string readOnly: true description: Generated short summary of the agent charter for listings. schedule: type: string nullable: true description: Cron-like schedule expression or interval (e.g., '@daily', '@every 30m'). maxLength: 128 schedule_snapshot: type: string readOnly: true nullable: true description: Snapshot of cron schedule for restoration. is_active: type: boolean description: Whether this agent is currently active life_state: allOf: - $ref: "#/components/schemas/LifeStateEnum" description: |- Lifecycle state for soft-expiration. 'paused' is represented by is_active=False. * `active` - Active * `expired` - Expired planning_state: allOf: - $ref: "#/components/schemas/PlanningStateEnum" readOnly: true description: |- Planning lifecycle state for prompt-led agent setup. * `planning` - Planning * `completed` - Completed * `skipped` - Skipped planning_plan: type: string readOnly: true description: Final plan captured when planning mode completes. planning_completed_at: type: string format: date-time readOnly: true nullable: true description: Timestamp when planning mode was completed through end_planning. whitelist_policy: allOf: - $ref: "#/components/schemas/WhitelistPolicyEnum" description: |- Controls who can message this agent and who the agent may contact. Manual: only addresses/numbers listed on the agent's allowlist (includes owner/org members by default). * `default` - Default (Owner or Org Members) * `manual` - Allowed Contacts List contact_approval_mode: allOf: - $ref: "#/components/schemas/ContactApprovalModeEnum" description: |- Controls whether new email recipients require per-contact approval or are automatically added to the agent's contact list. SMS always requires approval. * `require_approval` - Require approval * `auto_approve_email` - Automatically allow email contacts email_sending_mode: allOf: - $ref: "#/components/schemas/EmailSendingModeEnum" description: |- Requested email sending mode. Organization policy may enforce a stricter effective mode. * `review_all_external` - Review before send * `review_new_contacts` - Review only new contacts * `send_automatically` - Send automatically effective_email_sending_mode: type: string readOnly: true organization_minimum_email_sending_mode: type: string nullable: true readOnly: true last_interaction_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the last user interaction (reply, edit, etc.). created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true user_id: type: string readOnly: true description: Django user ID serialized as a decimal string. organization_id: type: string format: uuid readOnly: true nullable: true team_id: type: string format: uuid writeOnly: true nullable: true description: Creation placement in an active Team; member keys only. Immutable through agent update; use the guarded workspace endpoint. browser_use_agent_id: type: string format: uuid readOnly: true preferred_contact_endpoint_id: type: string format: uuid readOnly: true nullable: true preferred_contact_endpoint: type: string nullable: true description: An eligible endpoint UUID or email. Null clears the preference. writeOnly: true preferred_llm_tier: type: string nullable: true daily_credit_limit: type: integer readOnly: true nullable: true description: Deprecated stored credit target; inactive. Writes are rejected. proactive_opt_in: type: boolean description: Enable the platform to proactively start conversations offering related help for this agent. proactive_last_trigger_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the most recent proactive outreach trigger. template_code: type: string writeOnly: true nullable: true enabled_personal_server_ids: type: array items: type: string format: uuid writeOnly: true available_mcp_servers: type: array items: type: object additionalProperties: {} readOnly: true personal_mcp_server_ids: type: array items: type: string readOnly: true credit_controls_active: type: boolean readOnly: true default: false description: Always false. Credit fields are deprecated, inactive historical reads retained until an explicit breaking-release decision. PatchedPlacement: type: object properties: workspace_type: $ref: "#/components/schemas/WorkspaceTypeEnum" team_id: type: string format: uuid additionalProperties: false PatchedSchedulePatch: type: object properties: name: type: string maxLength: 120 instruction: type: string default: "" maxLength: 500 kind: $ref: "#/components/schemas/KindEnum" expression: type: string nullable: true maxLength: 128 timezone: type: string default: UTC maxLength: 64 run_at: type: string format: date-time nullable: true enabled: type: boolean default: true additionalProperties: false PatchedTaskUpdate: type: object properties: id: type: string format: uuid readOnly: true agent: type: string format: uuid nullable: true agent_id: type: string format: uuid readOnly: true organization_id: type: string format: uuid readOnly: true prompt: type: string nullable: true requires_vision: type: boolean description: When true, restricts browser tasks to vision-capable LLM endpoints only. output_schema: nullable: true description: Optional JSON schema to define structured output from the agent status: allOf: - $ref: "#/components/schemas/BrowserTaskStatus" readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true error_message: type: string readOnly: true nullable: true wait: type: integer maximum: 1350 minimum: 0 writeOnly: true secrets: type: object maxProperties: 20 additionalProperties: type: object minProperties: 1 additionalProperties: type: string minLength: 1 writeOnly: true description: "Pending, unclaimed tasks only: replace the entire domain-scoped credential map. Omission preserves it; {} clears it; null is invalid. No merge or credential readback." credits_cost: type: string format: decimal pattern: ^-?\d{0,9}(?:\.\d{0,3})?$ readOnly: true nullable: true description: Deprecated historical credit value; inactive. webhook: type: string format: uri nullable: true description: HTTP or HTTPS URL invoked when the task finishes. webhook_last_called_at: type: string format: date-time readOnly: true webhook_last_status_code: type: integer readOnly: true nullable: true webhook_last_error: type: string readOnly: true nullable: true credit_controls_active: type: boolean readOnly: true default: false description: Always false. Credit fields are deprecated, inactive historical reads retained until an explicit breaking-release decision. PeerAgentReference: type: object properties: id: type: string format: uuid name: type: string is_active: type: boolean life_state: type: string required: - id - is_active - life_state - name PeerLink: type: object properties: id: type: string format: uuid agent_a: $ref: "#/components/schemas/PeerAgentReference" agent_b: $ref: "#/components/schemas/PeerAgentReference" health: $ref: "#/components/schemas/PeerLinkHealth" is_enabled: type: boolean messages_per_window: type: integer maximum: 500 minimum: 1 window_hours: type: integer maximum: 168 minimum: 1 feature_flag: type: string nullable: true pair_key: type: string created_by_user_id: type: integer nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - agent_a - agent_b - created_at - created_by_user_id - feature_flag - health - id - is_enabled - messages_per_window - pair_key - updated_at - window_hours PeerLinkCreate: type: object properties: peer_agent_id: type: string format: uuid messages_per_window: type: integer maximum: 500 minimum: 1 default: 30 window_hours: type: integer maximum: 168 minimum: 1 default: 6 required: - peer_agent_id additionalProperties: false PeerLinkCreateResponse: type: object properties: link: $ref: "#/components/schemas/PeerLink" created: type: boolean required: - created - link PeerLinkHealth: type: object properties: status: $ref: "#/components/schemas/PeerLinkHealthStatusEnum" issues: type: array items: $ref: "#/components/schemas/PeerLinkHealthIssue" required: - issues - status PeerLinkHealthIssue: type: object properties: agent_id: type: string format: uuid reason: type: string required: - agent_id - reason PeerLinkHealthStatusEnum: enum: - healthy - unhealthy type: string description: |- * `healthy` - healthy * `unhealthy` - unhealthy PeerLinkListResponse: type: object properties: links: type: array items: $ref: "#/components/schemas/PeerLink" count: type: integer minimum: 0 required: - count - links PeerLinkResponse: type: object properties: link: $ref: "#/components/schemas/PeerLink" required: - link PendingAction: type: object properties: id: type: string type: type: string status: type: string created_at: type: string format: date-time nullable: true expires_at: type: string format: date-time nullable: true data: type: object additionalProperties: {} allowed_decisions: type: array items: type: string required: - allowed_decisions - created_at - data - expires_at - id - status - type PendingActionListResponse: type: object properties: actions: type: array items: $ref: "#/components/schemas/PendingAction" count: type: integer required: - actions - count PendingActionResolveRequest: type: object properties: decision: type: string name: type: string description: Name for an approved specialist agent; required when the organization requires agent names. maxLength: 255 selected_option_key: type: string free_text: type: string continue_without_answer: type: boolean value: type: string writeOnly: true version: type: integer minimum: 1 allow_inbound: type: boolean allow_outbound: type: boolean can_configure: type: boolean required: - decision PendingActionResolveResponse: type: object properties: action: $ref: "#/components/schemas/PendingAction" required: - action PersistentAgentArchivedList: type: object properties: id: type: string format: uuid readOnly: true name: type: string readOnly: true charter: type: string readOnly: true schedule: type: string readOnly: true nullable: true description: Cron-like schedule expression or interval (e.g., '@daily', '@every 30m'). is_active: type: boolean readOnly: true description: Whether this agent is currently active life_state: allOf: - $ref: "#/components/schemas/LifeStateEnum" readOnly: true description: |- Lifecycle state for soft-expiration. 'paused' is represented by is_active=False. * `active` - Active * `expired` - Expired planning_state: allOf: - $ref: "#/components/schemas/PlanningStateEnum" readOnly: true description: |- Planning lifecycle state for prompt-led agent setup. * `planning` - Planning * `completed` - Completed * `skipped` - Skipped planning_plan: type: string readOnly: true description: Final plan captured when planning mode completes. planning_completed_at: type: string format: date-time readOnly: true nullable: true description: Timestamp when planning mode was completed through end_planning. whitelist_policy: allOf: - $ref: "#/components/schemas/WhitelistPolicyEnum" readOnly: true description: |- Controls who can message this agent and who the agent may contact. Manual: only addresses/numbers listed on the agent's allowlist (includes owner/org members by default). * `default` - Default (Owner or Org Members) * `manual` - Allowed Contacts List contact_approval_mode: allOf: - $ref: "#/components/schemas/ContactApprovalModeEnum" readOnly: true description: |- Controls whether new email recipients require per-contact approval or are automatically added to the agent's contact list. SMS always requires approval. * `require_approval` - Require approval * `auto_approve_email` - Automatically allow email contacts email_sending_mode: allOf: - $ref: "#/components/schemas/EmailSendingModeEnum" readOnly: true description: |- Requested email sending mode. Organization policy may enforce a stricter effective mode. * `review_all_external` - Review before send * `review_new_contacts` - Review only new contacts * `send_automatically` - Send automatically effective_email_sending_mode: type: string readOnly: true organization_minimum_email_sending_mode: type: string nullable: true readOnly: true last_interaction_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the last user interaction (reply, edit, etc.). created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true user_id: type: string readOnly: true description: Django user ID serialized as a decimal string. organization_id: type: string format: uuid readOnly: true nullable: true browser_use_agent_id: type: string format: uuid readOnly: true preferred_contact_endpoint_id: type: string format: uuid readOnly: true nullable: true proactive_opt_in: type: boolean readOnly: true description: Enable the platform to proactively start conversations offering related help for this agent. proactive_last_trigger_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the most recent proactive outreach trigger. is_deleted: type: boolean readOnly: true deleted_at: type: string format: date-time readOnly: true nullable: true PersistentAgentDebugTraceResponse: type: object properties: agent: type: object additionalProperties: {} scope: type: object additionalProperties: {} timeline: type: object additionalProperties: {} audit_events: type: array items: type: object additionalProperties: {} audit: type: object additionalProperties: {} completions: type: object additionalProperties: {} eval_debug_artifacts: type: object additionalProperties: {} diagnostics: type: object additionalProperties: {} redaction: type: object additionalProperties: {} warnings: type: array items: type: string required: - agent - redaction - scope - warnings PersistentAgentDetail: type: object properties: id: type: string format: uuid readOnly: true name: type: string description: Display name. Required when the organization requires agent names; otherwise a name is generated when omitted. maxLength: 255 charter: type: string short_description: type: string readOnly: true description: Generated short summary of the agent charter for listings. schedule: type: string nullable: true description: Cron-like schedule expression or interval (e.g., '@daily', '@every 30m'). maxLength: 128 schedule_snapshot: type: string readOnly: true nullable: true description: Snapshot of cron schedule for restoration. is_active: type: boolean description: Whether this agent is currently active life_state: allOf: - $ref: "#/components/schemas/LifeStateEnum" description: |- Lifecycle state for soft-expiration. 'paused' is represented by is_active=False. * `active` - Active * `expired` - Expired planning_state: allOf: - $ref: "#/components/schemas/PlanningStateEnum" readOnly: true description: |- Planning lifecycle state for prompt-led agent setup. * `planning` - Planning * `completed` - Completed * `skipped` - Skipped planning_plan: type: string readOnly: true description: Final plan captured when planning mode completes. planning_completed_at: type: string format: date-time readOnly: true nullable: true description: Timestamp when planning mode was completed through end_planning. whitelist_policy: allOf: - $ref: "#/components/schemas/WhitelistPolicyEnum" description: |- Controls who can message this agent and who the agent may contact. Manual: only addresses/numbers listed on the agent's allowlist (includes owner/org members by default). * `default` - Default (Owner or Org Members) * `manual` - Allowed Contacts List contact_approval_mode: allOf: - $ref: "#/components/schemas/ContactApprovalModeEnum" description: |- Controls whether new email recipients require per-contact approval or are automatically added to the agent's contact list. SMS always requires approval. * `require_approval` - Require approval * `auto_approve_email` - Automatically allow email contacts email_sending_mode: allOf: - $ref: "#/components/schemas/EmailSendingModeEnum" description: |- Requested email sending mode. Organization policy may enforce a stricter effective mode. * `review_all_external` - Review before send * `review_new_contacts` - Review only new contacts * `send_automatically` - Send automatically effective_email_sending_mode: type: string readOnly: true organization_minimum_email_sending_mode: type: string nullable: true readOnly: true last_interaction_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the last user interaction (reply, edit, etc.). created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true user_id: type: string readOnly: true description: Django user ID serialized as a decimal string. organization_id: type: string format: uuid readOnly: true nullable: true team_id: type: string format: uuid writeOnly: true nullable: true description: Creation placement in an active Team; member keys only. Immutable through agent update; use the guarded workspace endpoint. browser_use_agent_id: type: string format: uuid readOnly: true preferred_contact_endpoint_id: type: string format: uuid readOnly: true nullable: true preferred_contact_endpoint: type: string nullable: true description: An eligible endpoint UUID or email. Null clears the preference. writeOnly: true preferred_llm_tier: type: string nullable: true daily_credit_limit: type: integer readOnly: true nullable: true description: Deprecated stored credit target; inactive. Writes are rejected. proactive_opt_in: type: boolean description: Enable the platform to proactively start conversations offering related help for this agent. proactive_last_trigger_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the most recent proactive outreach trigger. template_code: type: string writeOnly: true nullable: true enabled_personal_server_ids: type: array items: type: string format: uuid writeOnly: true available_mcp_servers: type: array items: type: object additionalProperties: {} readOnly: true personal_mcp_server_ids: type: array items: type: string readOnly: true credit_controls_active: type: boolean readOnly: true default: false description: Always false. Credit fields are deprecated, inactive historical reads retained until an explicit breaking-release decision. PersistentAgentEventWaitFilter: type: object properties: from_actor_type: $ref: "#/components/schemas/FromActorTypeEnum" from_agent_id: type: string format: uuid to_agent_id: type: string format: uuid message_id: type: string format: uuid peer_link_id: type: string format: uuid channel: type: string status: type: string tool_name: type: string additionalProperties: false PersistentAgentEventWaitRequest: type: object properties: after_cursor: type: string nullable: true timeout_seconds: type: integer maximum: 30 minimum: 0 default: 10 limit: type: integer maximum: 100 minimum: 1 default: 20 event_types: type: array items: $ref: "#/components/schemas/TimelineWaitEventType" filters: $ref: "#/components/schemas/PersistentAgentEventWaitFilter" additionalProperties: false PersistentAgentEventWaitResponse: type: object properties: matched: type: boolean timed_out: type: boolean events: type: array items: type: object additionalProperties: {} next_cursor: type: string nullable: true latest_cursor: type: string nullable: true waited_seconds: type: number format: double minimum: 0 required: - events - latest_cursor - matched - next_cursor - timed_out - waited_seconds PersistentAgentList: type: object properties: id: type: string format: uuid readOnly: true name: type: string readOnly: true charter: type: string readOnly: true schedule: type: string readOnly: true nullable: true description: Cron-like schedule expression or interval (e.g., '@daily', '@every 30m'). is_active: type: boolean readOnly: true description: Whether this agent is currently active life_state: allOf: - $ref: "#/components/schemas/LifeStateEnum" readOnly: true description: |- Lifecycle state for soft-expiration. 'paused' is represented by is_active=False. * `active` - Active * `expired` - Expired planning_state: allOf: - $ref: "#/components/schemas/PlanningStateEnum" readOnly: true description: |- Planning lifecycle state for prompt-led agent setup. * `planning` - Planning * `completed` - Completed * `skipped` - Skipped planning_plan: type: string readOnly: true description: Final plan captured when planning mode completes. planning_completed_at: type: string format: date-time readOnly: true nullable: true description: Timestamp when planning mode was completed through end_planning. whitelist_policy: allOf: - $ref: "#/components/schemas/WhitelistPolicyEnum" readOnly: true description: |- Controls who can message this agent and who the agent may contact. Manual: only addresses/numbers listed on the agent's allowlist (includes owner/org members by default). * `default` - Default (Owner or Org Members) * `manual` - Allowed Contacts List contact_approval_mode: allOf: - $ref: "#/components/schemas/ContactApprovalModeEnum" readOnly: true description: |- Controls whether new email recipients require per-contact approval or are automatically added to the agent's contact list. SMS always requires approval. * `require_approval` - Require approval * `auto_approve_email` - Automatically allow email contacts email_sending_mode: allOf: - $ref: "#/components/schemas/EmailSendingModeEnum" readOnly: true description: |- Requested email sending mode. Organization policy may enforce a stricter effective mode. * `review_all_external` - Review before send * `review_new_contacts` - Review only new contacts * `send_automatically` - Send automatically effective_email_sending_mode: type: string readOnly: true organization_minimum_email_sending_mode: type: string nullable: true readOnly: true last_interaction_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the last user interaction (reply, edit, etc.). created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true user_id: type: string readOnly: true description: Django user ID serialized as a decimal string. organization_id: type: string format: uuid readOnly: true nullable: true browser_use_agent_id: type: string format: uuid readOnly: true preferred_contact_endpoint_id: type: string format: uuid readOnly: true nullable: true proactive_opt_in: type: boolean readOnly: true description: Enable the platform to proactively start conversations offering related help for this agent. proactive_last_trigger_at: type: string format: date-time readOnly: true nullable: true description: Timestamp of the most recent proactive outreach trigger. PersistentAgentMessageCreate: type: object properties: channel: $ref: "#/components/schemas/PersistentAgentMessageCreateChannelEnum" sender: type: string maxLength: 512 recipient: type: string nullable: true maxLength: 512 subject: type: string nullable: true description: Email subject, preserved in history and agent context. Omitted, null or blank means no subject. Nonblank subjects require the email channel for new submissions; historical replays are unchanged. maxLength: 512 body: type: string metadata: type: object additionalProperties: {} required: - body - channel - sender PersistentAgentMessageCreateChannelEnum: enum: - email - slack - discord - web - other type: string description: |- * `email` - Email * `slack` - Slack * `discord` - Discord * `web` - Web Chat * `other` - Other PersistentAgentProcessingSnapshot: type: object properties: active: type: boolean webTasks: type: array items: type: object additionalProperties: {} nextScheduledAt: type: string format: date-time nullable: true required: - active - nextScheduledAt - webTasks PersistentAgentProcessingStatusResponse: type: object properties: processing_active: type: boolean processing_snapshot: $ref: "#/components/schemas/PersistentAgentProcessingSnapshot" required: - processing_active - processing_snapshot PersistentAgentRestoreConflict: type: object properties: detail: type: string errors: type: object additionalProperties: {} required: - detail - errors PersistentAgentRestoreResponse: type: object properties: restored: type: boolean agent: $ref: "#/components/schemas/PersistentAgentDetail" required: - agent - restored PersistentAgentSchedulePreview: type: object properties: schedule: type: string nullable: true required: - schedule PersistentAgentSchedulePreviewResponse: type: object properties: valid: type: boolean disabled: type: boolean description: type: string nullable: true required: - description - disabled - valid PersistentAgentStopResponse: type: object properties: stopping: type: boolean cancelled_web_task_count: type: integer minimum: 0 processing_active: type: boolean processing_snapshot: $ref: "#/components/schemas/PersistentAgentProcessingSnapshot" required: - cancelled_web_task_count - processing_active - processing_snapshot - stopping PingResponse: type: object properties: pong: type: boolean user: type: string format: email required: - pong - user PlanningStateEnum: enum: - planning - completed - skipped type: string description: |- * `planning` - Planning * `completed` - Completed * `skipped` - Skipped PublicationStateEnum: enum: - pending - queued - blocked type: string description: |- * `pending` - pending * `queued` - queued * `blocked` - blocked RedeliveryInput: type: object properties: expected_revision: type: integer minimum: 1 reason: type: string maxLength: 255 acknowledge_duplicate_risk: type: boolean default: false required: - expected_revision - reason RequestVisibilityEnum: enum: - principal - all type: string description: |- * `principal` - principal * `all` - all ResponseStateEnum: enum: - none - responded - closed_without_reply type: string description: |- * `none` - none * `responded` - responded * `closed_without_reply` - closed_without_reply RunMetadata: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid agent_id: type: string format: uuid status: type: string description: Recorded runtime status; does not prove an external effect succeeded. coverage_quality: type: string trigger_type: type: string started_at: type: string format: date-time ended_at: type: string format: date-time nullable: true processing_step_id: type: string format: uuid nullable: true application_request_ids: type: array items: type: string format: uuid request_links_truncated: type: boolean required: - agent_id - application_request_ids - coverage_quality - ended_at - id - organization_id - processing_step_id - request_links_truncated - started_at - status - trigger_type RunPage: type: object properties: schema_version: type: integer period: {} results: type: array items: $ref: "#/components/schemas/RunMetadata" next_cursor: type: string nullable: true retention: type: string required: - next_cursor - period - results - retention - schema_version ScanStatusEnum: enum: - pending - scanning - retrying - clean - infected - unavailable - not_required type: string description: |- * `pending` - pending * `scanning` - scanning * `retrying` - retrying * `clean` - clean * `infected` - infected * `unavailable` - unavailable * `not_required` - not_required Schedule: type: object properties: id: type: string format: uuid readOnly: true schedule_key: type: string readOnly: true description: Stable agent-scoped identifier used when updating this schedule. name: type: string readOnly: true instruction: type: string readOnly: true description: What the agent should do when this schedule fires. kind: allOf: - $ref: "#/components/schemas/KindEnum" readOnly: true expression: type: string readOnly: true nullable: true description: Cron or @every expression for a recurring schedule. timezone: type: string readOnly: true description: IANA timezone used to interpret recurring cron expressions. run_at: type: string format: date-time readOnly: true nullable: true description: Exact timezone-aware instant for a one-time schedule. enabled: type: boolean readOnly: true next_run_at: type: string format: date-time readOnly: true nullable: true last_fired_at: type: string format: date-time readOnly: true nullable: true revision: type: integer readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true ScheduleInput: type: object properties: schedule_key: type: string maxLength: 64 pattern: ^[a-z0-9][a-z0-9_-]{0,63}$ name: type: string maxLength: 120 instruction: type: string default: "" maxLength: 500 kind: $ref: "#/components/schemas/KindEnum" expression: type: string nullable: true maxLength: 128 timezone: type: string default: UTC maxLength: 64 run_at: type: string format: date-time nullable: true enabled: type: boolean default: true required: - kind - name - schedule_key additionalProperties: false SchedulePage: type: object properties: results: type: array items: $ref: "#/components/schemas/Schedule" required: - results SourceEvent: type: object properties: id: type: string format: uuid type: type: string sequence: type: integer occurred_at: type: string format: date-time captured_at: type: string format: date-time available: type: boolean envelope: {} required: - available - captured_at - id - occurred_at - sequence - type SourceEventPage: type: object properties: results: type: array items: $ref: "#/components/schemas/SourceEvent" cursor: type: string next_cursor: type: string nullable: true reconciliation_urls: type: object additionalProperties: type: string required: - cursor - next_cursor - reconciliation_urls - results StateEnum: enum: - not_requested - pending - validated - validation_failed - generation_failed - no_result - purged type: string description: |- * `not_requested` - not_requested * `pending` - pending * `validated` - validated * `validation_failed` - validation_failed * `generation_failed` - generation_failed * `no_result` - no_result * `purged` - purged TaskCreateResponse: type: object properties: id: type: string format: uuid readOnly: true agent: type: string format: uuid nullable: true agent_id: type: string format: uuid readOnly: true organization_id: type: string format: uuid readOnly: true prompt: type: string nullable: true requires_vision: type: boolean description: When true, restricts browser tasks to vision-capable LLM endpoints only. output_schema: nullable: true description: Optional JSON schema to define structured output from the agent status: allOf: - $ref: "#/components/schemas/BrowserTaskStatus" readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true error_message: type: string readOnly: true nullable: true wait: type: integer maximum: 1350 minimum: 0 writeOnly: true secrets: type: object maxProperties: 20 additionalProperties: type: object minProperties: 1 additionalProperties: type: string minLength: 1 minProperties: 1 writeOnly: true description: Write-only nonempty domain-to-secret map for task creation. Domain values are nonempty maps of placeholder names to string credentials. Null and empty maps are rejected. credits_cost: type: string format: decimal pattern: ^-?\d{0,9}(?:\.\d{0,3})?$ readOnly: true nullable: true description: Deprecated historical credit value; inactive. webhook: type: string format: uri nullable: true description: HTTP or HTTPS URL invoked when the task finishes. webhook_last_called_at: type: string format: date-time readOnly: true webhook_last_status_code: type: integer readOnly: true nullable: true webhook_last_error: type: string readOnly: true nullable: true result: readOnly: true nullable: true wait_error: type: string readOnly: true credit_controls_active: type: boolean readOnly: true default: false description: Always false. Credit fields are deprecated, inactive historical reads retained until an explicit breaking-release decision. TaskDetail: type: object properties: id: type: string format: uuid readOnly: true agent: type: string format: uuid nullable: true agent_id: type: string format: uuid readOnly: true organization_id: type: string format: uuid readOnly: true prompt: type: string nullable: true requires_vision: type: boolean description: When true, restricts browser tasks to vision-capable LLM endpoints only. output_schema: nullable: true description: Optional JSON schema to define structured output from the agent status: allOf: - $ref: "#/components/schemas/BrowserTaskStatus" readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true error_message: type: string readOnly: true nullable: true wait: type: integer maximum: 1350 minimum: 0 writeOnly: true secrets: type: object maxProperties: 20 additionalProperties: type: object minProperties: 1 additionalProperties: type: string minLength: 1 minProperties: 1 writeOnly: true description: Write-only nonempty domain-to-secret map for task creation. Domain values are nonempty maps of placeholder names to string credentials. Null and empty maps are rejected. credits_cost: type: string format: decimal pattern: ^-?\d{0,9}(?:\.\d{0,3})?$ readOnly: true nullable: true description: Deprecated historical credit value; inactive. webhook: type: string format: uri nullable: true description: HTTP or HTTPS URL invoked when the task finishes. webhook_last_called_at: type: string format: date-time readOnly: true webhook_last_status_code: type: integer readOnly: true nullable: true webhook_last_error: type: string readOnly: true nullable: true credit_controls_active: type: boolean readOnly: true default: false description: Always false. Credit fields are deprecated, inactive historical reads retained until an explicit breaking-release decision. TaskList: type: object properties: id: type: string format: uuid readOnly: true agent_id: type: string format: uuid readOnly: true prompt: type: string readOnly: true nullable: true requires_vision: type: boolean readOnly: true description: When true, restricts browser tasks to vision-capable LLM endpoints only. output_schema: readOnly: true nullable: true description: Optional JSON schema to define structured output from the agent status: allOf: - $ref: "#/components/schemas/BrowserTaskStatus" readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true credits_cost: type: string format: decimal pattern: ^-?\d{0,9}(?:\.\d{0,3})?$ readOnly: true nullable: true description: Credits charged for this task; defaults to configured per‑task cost. webhook: type: string format: uri readOnly: true nullable: true credit_controls_active: type: boolean readOnly: true default: false description: Always false. Credit fields are deprecated, inactive historical reads retained until an explicit breaking-release decision. TaskUpdate: type: object properties: id: type: string format: uuid readOnly: true agent: type: string format: uuid nullable: true agent_id: type: string format: uuid readOnly: true organization_id: type: string format: uuid readOnly: true prompt: type: string nullable: true requires_vision: type: boolean description: When true, restricts browser tasks to vision-capable LLM endpoints only. output_schema: nullable: true description: Optional JSON schema to define structured output from the agent status: allOf: - $ref: "#/components/schemas/BrowserTaskStatus" readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true error_message: type: string readOnly: true nullable: true wait: type: integer maximum: 1350 minimum: 0 writeOnly: true secrets: type: object maxProperties: 20 additionalProperties: type: object minProperties: 1 additionalProperties: type: string minLength: 1 writeOnly: true description: "Pending, unclaimed tasks only: replace the entire domain-scoped credential map. Omission preserves it; {} clears it; null is invalid. No merge or credential readback." credits_cost: type: string format: decimal pattern: ^-?\d{0,9}(?:\.\d{0,3})?$ readOnly: true nullable: true description: Deprecated historical credit value; inactive. webhook: type: string format: uri nullable: true description: HTTP or HTTPS URL invoked when the task finishes. webhook_last_called_at: type: string format: date-time readOnly: true webhook_last_status_code: type: integer readOnly: true nullable: true webhook_last_error: type: string readOnly: true nullable: true credit_controls_active: type: boolean readOnly: true default: false description: Always false. Credit fields are deprecated, inactive historical reads retained until an explicit breaking-release decision. TimelineWaitEventType: enum: - message - plan - steps - thinking type: string description: |- * `message` - message * `plan` - plan * `steps` - steps * `thinking` - thinking UsagePage: type: object properties: schema_version: type: integer period: {} results: type: array items: $ref: "#/components/schemas/UsageRow" next_cursor: type: string nullable: true retention: type: string required: - next_cursor - period - results - retention - schema_version UsageRow: type: object properties: id: type: string format: uuid organization_id: type: string format: uuid nullable: true agent_id: type: string format: uuid nullable: true owner_id: type: string nullable: true team_id: type: string format: uuid nullable: true created_at: type: string format: date-time run_id: type: string format: uuid nullable: true model_attempt_id: type: string format: uuid nullable: true processing_step_id: type: string format: uuid nullable: true trigger_id: type: string format: uuid nullable: true browser_task_id: type: string format: uuid nullable: true purpose: type: string configured_model: type: string configured_provider: type: string returned_model: type: string nullable: true reported_provider: type: string nullable: true outcome: type: string duration_ms: type: integer nullable: true tokens: type: object additionalProperties: type: integer nullable: true description: Nullable measured/derived token counters; missing is not zero. measurement: description: Allowlisted retained normalization source, coverage, derivation and warnings. pricing: description: Original retained USD rates per million tokens and source/revision; never repriced. estimated_cost: type: string nullable: true description: Exact decimal USD estimate using retained public/customer pricing; not an invoice. reported_cost: type: string nullable: true description: Exact decimal USD provider-reported amount, separately observed. application_request_ids: type: array items: type: string format: uuid request_links_truncated: type: boolean required: - agent_id - application_request_ids - browser_task_id - configured_model - configured_provider - created_at - duration_ms - estimated_cost - id - measurement - model_attempt_id - organization_id - outcome - owner_id - pricing - processing_step_id - purpose - reported_cost - reported_provider - request_links_truncated - returned_model - run_id - team_id - tokens - trigger_id UsageSummary: type: object properties: schema_version: type: integer period: {} metrics: description: Authorized retained dispatch count, known token subtotals/coverage and separate estimated/reported USD subtotals. retention: type: string required: - metrics - period - retention - schema_version VersionedRestError: type: object required: - error properties: error: type: object required: - code - request_id - action - field_codes - details properties: code: type: string request_id: type: string format: uuid action: type: string enum: - correct_input - reauthenticate - remediate_permissions - refresh_state - reconcile - retry_read - retry_same_operation field_codes: {} details: {} WebhookEventType: enum: - agent.message - agent.message.created - agent.request.updated - agent.request.responded - agent.pending_action.created - agent.pending_action.resolved - agent.pending_action.expired - agent.pending_action.* - "*" type: string description: |- * `agent.message` - agent.message * `agent.message.created` - agent.message.created * `agent.request.updated` - agent.request.updated * `agent.request.responded` - agent.request.responded * `agent.pending_action.created` - agent.pending_action.created * `agent.pending_action.resolved` - agent.pending_action.resolved * `agent.pending_action.expired` - agent.pending_action.expired * `agent.pending_action.*` - agent.pending_action.* * `*` - * WhitelistPolicyEnum: enum: - default - manual type: string description: |- * `default` - Default (Owner or Org Members) * `manual` - Allowed Contacts List WorkspaceTypeEnum: enum: - personal - organization_private - team type: string description: |- * `personal` - personal * `organization_private` - organization_private * `team` - team securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key SecurityServiceBearer: type: http scheme: bearer bearerFormat: dtsi.credential-uuid.secret cookieAuth: type: apiKey in: cookie name: sessionid tokenAuth: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token" servers: - url: http://localhost:8000/api/v1 description: Configured server tags: - name: Usage description: Scoped retained inference accounting with nullable counters and original decimal pricing snapshots; deployment-gated. - name: Audit metadata description: Scoped run metadata and known own-principal request links, separate from protected evidence; deployment-gated. - name: Named schedules description: Deterministic named-schedule CRUD, revision conditions and retained retry outcomes. - name: Agent setup description: Member-only inactive configuration, workspace placement and permitted integration binding metadata/handoffs. - name: Files description: Gated private file upload/replacement, bounded inventory/status and exact-generation or immutable attachment downloads. - name: Agent events description: Scoped retained automatic event catch-up, delivery diagnostics and deliberate recovery; prospective capture is deployment-gated. - name: Application requests description: Principal-addressed application input, owned responses, and revision waits; new admission is deployment-gated. - name: Operation outcomes description: Authorized reconciliation of retained retry outcomes without secret response bodies. - name: Agents API description: Persistent agent endpoints for creating, scheduling, messaging, and managing agents through the API. - name: Security interventions description: Scoped security service identities can request durable agent halts and read containment evidence. Recovery requires an authorized human in the Console. - name: browser-use Tasks API description: Legacy browser-use agent and task endpoints for submitting browser automation jobs, polling status, and retrieving results. - name: Utilities description: Utility endpoints for health checks and simple Decision Terrain API integration verification.