openapi: 3.2.0
info:
  title: Tale Platform Browser sessions API
  version: 3.27.0
  contact:
    name: Tale
    url: https://tale.dev
  description: 'REST access to a Tale deployment: knowledge resources, automations and their

    runs, chat threads, agents, and skills — plus an MCP endpoint exposing the

    same platform to MCP clients.'
servers:
- url: '{origin}'
  description: The deployment this document describes — `GET /openapi.json` on a running instance fills it in
  variables:
    origin:
      default: https://your-host.example.com
      description: Scheme and host of the Tale deployment
security:
- bearerAuth: []
tags:
- name: Browser sessions
  description: The warmed browser-session pool behind video-link ingestion.
paths:
  /api/v1/browser-sessions:
    get:
      tags:
      - Browser sessions
      summary: List browser sessions
      description: 'The organization’s warmed browser-session pool — the cookie jars the video-link ingest presents to get past a platform’s bot wall, with each session’s status, expiry and strike count. Masked: the jar itself is never returned. A complete set, not paginated.'
      operationId: listBrowserSessions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The pool
          content:
            application/json:
              schema:
                type: object
                description: 'The complete set under `sessions` — never paginated: no `isDone`, no cursor to follow'
                x-tale-pagination: none
                required:
                - sessions
                properties:
                  sessions:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrowserSession'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '304':
          description: Not Modified — `If-None-Match` named the current `ETag`, so the body is not sent
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '400':
          description: 'Invalid request: a body the schema refuses — a wrong type, an unknown key, a missing field, a NUL or an unpaired surrogate, a whole number beyond 2^53 − 1 (`INVALID_BODY`, every problem under `data.issues`); a query parameter the operation does not take, given twice or left blank (`INVALID_QUERY`); on a list, a `limit` that is not a whole number (`INVALID_LIMIT`) or a `cursor` this list did not answer (`INVALID_CURSOR`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '401':
          description: Missing or invalid API key (`UNAUTHORIZED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
        '403':
          description: '`X-Organization-Slug` names an organization the key holder is no member of (`ORG_FORBIDDEN`, with the slugs the key holder may send under `data.organizations`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '404':
          description: '`X-Organization-Slug` names no organization (`ORG_SLUG_INVALID`, with the slugs the key holder may send under `data.organizations`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '405':
          description: The path exists, but not for this method (`METHOD_NOT_ALLOWED`); `Allow` names the methods it serves
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Allow:
              $ref: '#/components/headers/Allow'
        '429':
          description: 'The key holder’s request budget is spent (`RATE_LIMITED`): `Retry-After` names the wait in whole seconds and `data.retryAfterMs` in milliseconds; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: Internal error (`INTERNAL_ERROR`); the envelope carries a `requestId` to quote when reporting it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '503':
          description: 'The platform’s database is restarting or cannot be reached (`DATABASE_UNAVAILABLE`): `Retry-After` names the wait in whole seconds — retry with backoff; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
      parameters:
      - name: X-Organization-Slug
        in: header
        required: false
        schema:
          type: string
        description: The organization to operate on. STRICTLY REQUIRED on every call, reads included, when the key holder belongs to more than one organization — without it such requests are refused with 400 `ORG_SLUG_REQUIRED` (the dashboard’s last-active organization never steers a machine call). A slug that names no organization answers 404 `ORG_SLUG_INVALID`, one the key holder is no member of 403 `ORG_FORBIDDEN`. Single-organization keys may omit it; a blank or whitespace-only value reads as the header absent. Each of the three refusals lists the slugs the key holder may send under `data.organizations`; `GET /api/v1/me` answers them too.
      - name: X-Request-Id
        in: header
        required: false
        description: 'Your own correlation id, echoed back on the response and written to the platform’s log: up to 255 characters of letters, digits, `_`, `-` and `=`. Any other value is replaced by a fresh UUID (the response carries the id that was used), and uniqueness of an id you choose is yours to keep.'
        schema:
          type: string
          pattern: ^[A-Za-z0-9_=-]{1,255}$
  /api/v1/browser-sessions/import:
    post:
      tags:
      - Browser sessions
      summary: Import a browser session
      description: 'Adds a warmed cookie jar to the pool for one domain; the jar is encrypted before it is stored. Restricted to organization administrators whose e-mail is on the deployment editor allowlist (`TALE_DEPLOYMENT_CONFIG_ADMINS`) — anyone else answers 403 with a `code` naming the gate that refused, before the body is read. The domain is normalized to its hostname (`https://Example.COM/path` and `example.com` are one host) and held to the crawl-target policy: loopback, link-local, private-network and cloud-metadata hosts answer 400 `INVALID_SESSION`. A session lives 14 days unless `ttlMs` says otherwise, and never longer than 180 days; `DELETE /api/v1/browser-sessions/{id}` revokes it earlier. `GET /api/v1/me` says in advance whether this key passes the gate (`capabilities.deploymentEditor`).'
      operationId: importBrowserSession
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrowserSessionImport'
      responses:
        '201':
          description: Imported — the session’s id
          content:
            application/json:
              schema:
                type: object
                required:
                - sessionId
                properties:
                  sessionId:
                    type: string
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '400':
          description: Invalid body (`INVALID_BODY` — a blank domain or jar, a lifetime past 180 days, an unknown key) or a domain no session can be warmed for (`INVALID_SESSION`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '401':
          description: Missing or invalid API key (`UNAUTHORIZED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
        '403':
          description: The key holder may not write to the pool (`FORBIDDEN_INSTANCE_ADMIN` or `FORBIDDEN_DEPLOYMENT_EDITOR`); or `X-Organization-Slug` names an organization the key holder is no member of (`ORG_FORBIDDEN`, with the slugs the key holder may send under `data.organizations`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '404':
          description: '`X-Organization-Slug` names no organization (`ORG_SLUG_INVALID`, with the slugs the key holder may send under `data.organizations`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '405':
          description: The path exists, but not for this method (`METHOD_NOT_ALLOWED`); `Allow` names the methods it serves
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Allow:
              $ref: '#/components/headers/Allow'
        '413':
          description: The body exceeds this operation’s byte cap — 1 MiB unless the description says otherwise (`BODY_TOO_LARGE`); the envelope carries a `requestId`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '429':
          description: 'The key holder’s request budget is spent (`RATE_LIMITED`): `Retry-After` names the wait in whole seconds and `data.retryAfterMs` in milliseconds; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: Internal error (`INTERNAL_ERROR`); the envelope carries a `requestId` to quote when reporting it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '503':
          description: 'The platform’s database is restarting or cannot be reached (`DATABASE_UNAVAILABLE`): `Retry-After` names the wait in whole seconds — retry with backoff; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
      parameters:
      - name: X-Organization-Slug
        in: header
        required: false
        schema:
          type: string
        description: The organization to operate on. STRICTLY REQUIRED on every call, reads included, when the key holder belongs to more than one organization — without it such requests are refused with 400 `ORG_SLUG_REQUIRED` (the dashboard’s last-active organization never steers a machine call). A slug that names no organization answers 404 `ORG_SLUG_INVALID`, one the key holder is no member of 403 `ORG_FORBIDDEN`. Single-organization keys may omit it; a blank or whitespace-only value reads as the header absent. Each of the three refusals lists the slugs the key holder may send under `data.organizations`; `GET /api/v1/me` answers them too.
      - name: X-Request-Id
        in: header
        required: false
        description: 'Your own correlation id, echoed back on the response and written to the platform’s log: up to 255 characters of letters, digits, `_`, `-` and `=`. Any other value is replaced by a fresh UUID (the response carries the id that was used), and uniqueness of an id you choose is yours to keep.'
        schema:
          type: string
          pattern: ^[A-Za-z0-9_=-]{1,255}$
  /api/v1/browser-sessions/{id}:
    delete:
      tags:
      - Browser sessions
      summary: Revoke a browser session
      description: Removes one imported session — the jar is gone at once, whatever its lifetime — behind the same gate as the import (`GET /api/v1/me` answers it in advance as `capabilities.deploymentEditor`). An id the organization does not hold answers 404.
      operationId: deleteBrowserSession
      security:
      - bearerAuth: []
      parameters:
      - name: X-Organization-Slug
        in: header
        required: false
        schema:
          type: string
        description: The organization to operate on. STRICTLY REQUIRED on every call, reads included, when the key holder belongs to more than one organization — without it such requests are refused with 400 `ORG_SLUG_REQUIRED` (the dashboard’s last-active organization never steers a machine call). A slug that names no organization answers 404 `ORG_SLUG_INVALID`, one the key holder is no member of 403 `ORG_FORBIDDEN`. Single-organization keys may omit it; a blank or whitespace-only value reads as the header absent. Each of the three refusals lists the slugs the key holder may send under `data.organizations`; `GET /api/v1/me` answers them too.
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The session id the import answered
      - name: X-Request-Id
        in: header
        required: false
        description: 'Your own correlation id, echoed back on the response and written to the platform’s log: up to 255 characters of letters, digits, `_`, `-` and `=`. Any other value is replaced by a fresh UUID (the response carries the id that was used), and uniqueness of an id you choose is yours to keep.'
        schema:
          type: string
          pattern: ^[A-Za-z0-9_=-]{1,255}$
      responses:
        '204':
          description: Revoked
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '400':
          description: 'Invalid request: a body the schema refuses — a wrong type, an unknown key, a missing field, a NUL or an unpaired surrogate, a whole number beyond 2^53 − 1 (`INVALID_BODY`, every problem under `data.issues`); a query parameter the operation does not take, given twice or left blank (`INVALID_QUERY`); on a list, a `limit` that is not a whole number (`INVALID_LIMIT`) or a `cursor` this list did not answer (`INVALID_CURSOR`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '401':
          description: Missing or invalid API key (`UNAUTHORIZED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
        '403':
          description: The key holder may not write to the pool (`FORBIDDEN_INSTANCE_ADMIN` or `FORBIDDEN_DEPLOYMENT_EDITOR`); or `X-Organization-Slug` names an organization the key holder is no member of (`ORG_FORBIDDEN`, with the slugs the key holder may send under `data.organizations`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '404':
          description: No such session in this organization (`BROWSER_SESSION_NOT_FOUND`); or `X-Organization-Slug` names no organization (`ORG_SLUG_INVALID`, with the slugs the key holder may send under `data.organizations`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '405':
          description: The path exists, but not for this method (`METHOD_NOT_ALLOWED`); `Allow` names the methods it serves
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Allow:
              $ref: '#/components/headers/Allow'
        '429':
          description: 'The key holder’s request budget is spent (`RATE_LIMITED`): `Retry-After` names the wait in whole seconds and `data.retryAfterMs` in milliseconds; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: Internal error (`INTERNAL_ERROR`); the envelope carries a `requestId` to quote when reporting it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '503':
          description: 'The platform’s database is restarting or cannot be reached (`DATABASE_UNAVAILABLE`): `Retry-After` names the wait in whole seconds — retry with backoff; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
components:
  headers:
    RetryAfter:
      description: How long to wait before retrying, in whole seconds
      schema:
        type: integer
        minimum: 1
    WWWAuthenticate:
      description: 'The challenge RFC 9110 §11.6.1 requires of a 401: `Bearer`, or `Bearer error="invalid_token"` when a key was presented and refused'
      schema:
        type: string
    XTaleApiVersion:
      description: The version of this contract (`info.version`) the serving instance implements — semver for the wire
      schema:
        type: string
        example: 3.27.0
    ETag:
      description: 'A validator: over the answer’s bytes on a JSON read, the stored object’s tag on a download. Send it back as `If-None-Match` — as received; the weak and edge-suffixed forms match too — to be told 304 when nothing changed.'
      schema:
        type: string
    Allow:
      description: The methods this path serves, comma-separated
      schema:
        type: string
        example: GET, POST, HEAD, OPTIONS
    XRequestId:
      description: The request id the platform logged this call under — quote it when reporting a problem. Echoes a sane `X-Request-Id` the caller sent.
      schema:
        type: string
    CacheControl:
      description: '`private, no-cache` on a validated read and on a download: keep the answer, revalidate it before reuse, and let no shared cache keep it. Every other answer says `no-store`.'
      schema:
        type: string
  schemas:
    BrowserSession:
      type: object
      required:
      - id
      - domain
      - label
      - status
      - createdAt
      - expiresAt
      - lastUsedAt
      - failureCount
      properties:
        id:
          type: string
        domain:
          type: string
        label:
          type:
          - string
          - 'null'
        createdAt:
          type: integer
          minimum: 0
          description: When the session was imported
        status:
          type: string
          enum:
          - healthy
          - cooling
          - expired
          description: healthy = claimable; cooling = blocked once, recovers after a quiet period; expired = three strikes or past its TTL
        expiresAt:
          type: integer
          minimum: 0
          description: Epoch milliseconds
        lastUsedAt:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Epoch ms of the last claim
        failureCount:
          type: integer
    BrowserSessionImport:
      type: object
      required:
      - domain
      - cookiesJar
      additionalProperties: false
      properties:
        domain:
          type: string
          minLength: 1
          maxLength: 255
          description: The host the jar was warmed for — a hostname or an http(s) URL, normalized to its lower-cased hostname on import; private-network and metadata hosts are refused (400 `INVALID_SESSION`)
        cookiesJar:
          type: string
          minLength: 1
          maxLength: 1000000
          description: A Netscape-format cookie jar, at most 1 MB
        userAgent:
          type: string
          maxLength: 512
        visitorData:
          type: string
          maxLength: 2048
        poToken:
          type: string
          maxLength: 4096
        label:
          type: string
          maxLength: 120
        ttlMs:
          type: integer
          minimum: 1
          maximum: 15552000000
          description: Lifetime in milliseconds (default 1209600000, 14 days; at most 15552000000, 180 days)
    Error:
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
          description: What went wrong
        code:
          type: string
          enum:
          - ACTOR_AMBIGUOUS
          - ACTOR_DISABLED
          - ACTOR_FORBIDDEN
          - ACTOR_NOT_FOUND
          - ACTOR_REBOUND
          - ACTOR_UNVERIFIED
          - API_KEY_SCOPE_FORBIDDEN
          - ATTACHMENT_NOT_FOUND
          - ATTACHMENT_NOT_OWNED
          - ATTACHMENT_NOT_STAGED
          - ATTACHMENT_SIZE_MISMATCH
          - AUTHOR_UNVERIFIED
          - AUTOMATION_DELIVERY_SCOPE_MISMATCH
          - AUTOMATION_HAS_ACTIVE_RUNS
          - AUTOMATION_INPUT_INVALID
          - AUTOMATION_NOT_DEPLOYED
          - AUTOMATION_NOT_FOUND
          - AUTOMATION_NOT_INSTALLED
          - AUTOMATION_PROJECT_FORBIDDEN
          - AUTOMATION_PROJECT_SCOPE_REQUIRED
          - AUTOMATION_TRIGGER_INVALID
          - AUTOMATION_VERSION_NOT_DEPLOYED
          - AUTOMATION_VERSION_UNKNOWN
          - BLOB_NOT_FOUND
          - BODY_CHUNK_MALFORMED
          - BODY_LENGTH_MISMATCH
          - BODY_TOO_LARGE
          - BROWSER_SESSION_NOT_FOUND
          - BUDGET_EXCEEDED
          - CHAT_MODEL_AMBIGUOUS
          - CHAT_MODEL_NOT_ON_PROVIDER
          - CHAT_MODEL_UNKNOWN
          - CHAT_PROVIDER_UNKNOWN
          - CHAT_THREAD_ARCHIVED
          - CHAT_THREAD_NOT_DIRECT
          - CHAT_TURN_IN_PROGRESS
          - CHAT_TURN_NOT_RUNNING
          - CONTACT_AMBIGUOUS
          - CONTACT_DUPLICATE_EMAIL
          - CONTACT_DUPLICATE_EXTERNAL_ID
          - CONTACT_IDENTITY_REQUIRED
          - CONTACT_NOT_FOUND
          - CONTACT_STALE
          - CONVERSATION_CLOSED
          - CONVERSATION_CONTACT_CONFLICT
          - CONVERSATION_CONTACT_TRASHED
          - CONVERSATION_NOT_FOUND
          - CONVERSATION_SNAPSHOT_CONFLICT
          - CONVERSATION_SOURCE_NOT_FOUND
          - DATABASE_UNAVAILABLE
          - DELIVERY_NOT_FOUND
          - DELIVERY_RECEIPT_CONFLICT
          - DELIVERY_RETRY_UNAVAILABLE
          - DELIVERY_UNACKNOWLEDGED
          - DOCUMENT_HAS_KNOWLEDGE_ENTRY
          - DOCUMENT_NOT_FOUND
          - DOCUMENT_RECORD_FROZEN
          - DOCUMENT_RECORD_PROTECTED
          - DOCUMENT_RECORD_REPLACEMENT_REQUIRED
          - DOCUMENT_STALE
          - DUPLICATE_PRODUCT_EXTERNAL_ID
          - DUPLICATE_PRODUCT_NAME
          - EMBEDDING_CREDENTIAL_REJECTED
          - EMBEDDING_CREDIT_EXHAUSTED
          - EMBEDDING_NOT_CONFIGURED
          - EMBEDDING_UPSTREAM_ERROR
          - EMPTY_ANSWER
          - FILE_NOT_FOUND
          - FILE_SIZE_INVALID
          - FILE_TOO_LARGE
          - FOLDER_DEPTH_EXCEEDED
          - FOLDER_NAME_INVALID
          - FOLDER_NAME_TAKEN
          - FOLDER_NOT_ACCESSIBLE
          - FOLDER_NOT_FOUND
          - FORBIDDEN_DEPLOYMENT_EDITOR
          - FORBIDDEN_INSTANCE_ADMIN
          - HTTP_ERROR
          - HUMAN_ASK_EXPIRED
          - HUMAN_ASK_NOT_FOUND
          - HUMAN_ASK_NOT_PENDING
          - IDEMPOTENCY_KEY_REUSED
          - INTEGRATION_NOT_OWNED
          - INTERNAL_ERROR
          - INVALID_BODY
          - INVALID_CURSOR
          - INVALID_HEADER
          - INVALID_LIMIT
          - INVALID_QUERY
          - INVALID_SESSION
          - INVALID_SKILL
          - INVALID_SKILL_SLUG
          - INVALID_URL
          - KNOWLEDGE_ENTRY_DUPLICATE
          - KNOWLEDGE_ENTRY_FORBIDDEN
          - KNOWLEDGE_ENTRY_NOT_FOUND
          - KNOWLEDGE_ENTRY_STORE_TIMEOUT
          - KNOWLEDGE_ENTRY_SUPERSEDED
          - LEGAL_HOLD_ACTIVE
          - MENTION_DIRECTORY_UNAVAILABLE
          - MESSAGE_NOT_FOUND
          - METHOD_NOT_ALLOWED
          - MODEL_API_CONCURRENCY_EXCEEDED
          - MODEL_API_DISABLED
          - MODEL_API_FORBIDDEN
          - MODEL_API_GUARDRAIL_BLOCKED
          - MODEL_API_GUARDRAIL_UNAVAILABLE
          - MODEL_API_GUARDRAIL_UNSUPPORTED
          - MODEL_API_MODEL_FORBIDDEN
          - MODEL_API_MODEL_UNKNOWN
          - MODEL_API_TEXT_TOO_LARGE
          - MODEL_API_TOOLS_UNSUPPORTED
          - MODEL_API_UNAVAILABLE
          - MODEL_API_UPSTREAM_ERROR
          - MODEL_API_VENDOR_TOOL_UNSUPPORTED
          - MODEL_API_VISION_UNSUPPORTED
          - NOT_FOUND
          - OBJECT_STORE_UNAVAILABLE
          - OBJECT_STORE_UNCONFIGURED
          - ORG_FORBIDDEN
          - ORG_SLUG_INVALID
          - ORG_SLUG_REQUIRED
          - ORIGIN_FORBIDDEN
          - PRECONDITION_FAILED
          - PRODUCT_NOT_FOUND
          - PRODUCT_STALE
          - PROJECT_AGENT_CONNECTOR_UNKNOWN
          - PROJECT_AGENT_HARNESS_INVALID
          - PROJECT_AGENT_LIMIT
          - PROJECT_AGENT_MANAGED
          - PROJECT_AGENT_MODEL_INVALID
          - PROJECT_AGENT_NAME_TAKEN
          - PROJECT_AGENT_NOT_FOUND
          - PROJECT_AGENT_PROVIDER_UNKNOWN
          - PROJECT_AGENT_SECRETS_FORBIDDEN
          - PROJECT_AGENT_SECRET_UNKNOWN
          - PROJECT_AGENT_SKILL_UNKNOWN
          - PROJECT_AGENT_STALE
          - PROJECT_AGENT_TOOL_UNKNOWN
          - PROJECT_ARCHIVED
          - PROJECT_DUPLICATE_EXTERNAL_ID
          - PROJECT_FORBIDDEN
          - PROJECT_HAS_BOUND_AUTOMATIONS
          - PROJECT_HAS_PROTECTED_RECORDS
          - PROJECT_KEY_INVALID
          - PROJECT_KEY_TAKEN
          - PROJECT_LEGAL_HOLD
          - PROJECT_NOT_FOUND
          - PROJECT_SHARING_INVALID
          - PURGE_INCOMPLETE
          - RATE_LIMITED
          - RBAC_FORBIDDEN
          - REQUEST_TIMEOUT
          - REVIEW_COMPETENCE_REQUIRED
          - REVIEW_INDEPENDENT_REVIEWER_REQUIRED
          - ROLE_FORBIDDEN
          - RUN_ACTIVE
          - RUN_NOT_FOUND
          - RUN_QUARANTINED
          - RUN_QUARANTINE_CHANGED
          - SETUP_FOLDER_MISSING
          - SKILL_EXISTS
          - SKILL_FILE_NOT_FOUND
          - SKILL_FORBIDDEN
          - SKILL_MALFORMED
          - SKILL_NOT_FOUND
          - SKILL_PUBLISH_FORBIDDEN
          - SKILL_STALE
          - SKILL_TEAM_UNKNOWN
          - STANDARD_AGENT_OFF
          - STANDARD_AGENT_UNAVAILABLE
          - TASK_AGENT_REVIEW_REQUIRED
          - TASK_ARCHIVED
          - TASK_AUTOMATION_DISABLED
          - TASK_AUTOMATION_UNAVAILABLE
          - TASK_EXTERNAL_REF_INVALID
          - TASK_EXTERNAL_STATUS_STALE
          - TASK_HAS_LIVE_RUN
          - TASK_HAS_OPEN_SUBTASKS
          - TASK_LABEL_UNKNOWN
          - TASK_NOT_FOUND
          - TASK_NOT_IN_REVIEW
          - TASK_REVIEW_POLICY_UNAVAILABLE
          - TASK_STATUS_CONFLICT
          - TEAM_ACCESS_DENIED
          - TEAM_INHERITED_FROM_FOLDER
          - TEAM_NOT_IN_ORG
          - THREAD_NOT_FOUND
          - UNAUTHORIZED
          - UNSUPPORTED_FILE_TYPE
          - UPLOAD_FILE_MISMATCH
          - UPLOAD_INTENT_INVALID
          - UPLOAD_POLICY_REJECTED
          - UPSTREAM_UNAVAILABLE
          - URI_TOO_LONG
          - WEBSITE_DOMAIN_IMMUTABLE
          - WEBSITE_DOMAIN_INVALID
          - WEBSITE_DOMAIN_NOT_CRAWLABLE
          - WEBSITE_DUPLICATE_DOMAIN
          - WEBSITE_INVALID_LIST_URL
          - WEBSITE_NOT_FOUND
          description: 'A stable refusal code — every refusal the door itself makes carries one, and so does every domain refusal it lets through. The set is additive: a new code is a minor change, so treat a value you do not know as a generic refusal of the status you got.'
        requestId:
          type: string
          description: The response’s `X-Request-Id`, repeated on a 429, on a 500, on a body-size 413 and on a URL-size 414 so a caller can quote it
        data:
          type: object
          properties:
            retryAfterMs:
              type: number
              description: Wait in milliseconds for RATE_LIMITED
            providers:
              type: array
              items:
                type: string
              description: For CHAT_MODEL_AMBIGUOUS, the provider slugs that serve the model — name one as `providerSlug`
            lastMessageId:
              type: string
              description: 'For CHAT_TURN_NOT_RUNNING, the newest assistant message on the thread (once it has one) — the idle poll’s own disambiguation: equal to the `messageId` a 202 named means that turn already settled'
            lastStatus:
              type: string
              enum:
              - pending
              - complete
              - failed
              - cancelled
              description: For CHAT_TURN_NOT_RUNNING, how `lastMessageId` settled (present with it)
            organizations:
              type: array
              description: For ORG_SLUG_REQUIRED, ORG_SLUG_INVALID and ORG_FORBIDDEN, the organizations the key holder belongs to (a disabled membership is left out; the list is empty when none remains) — send one of the slugs as `X-Organization-Slug`
              items:
                type: object
                required:
                - slug
                - name
                properties:
                  slug:
                    type: string
                  name:
                    type: string
            issues:
              type: array
              description: For INVALID_BODY and INVALID_QUERY, every problem the schema found in the body or the query string; for INVALID_LIMIT and INVALID_CURSOR, the one parameter refused (`limit`, `cursor`); for AUTOMATION_INPUT_INVALID, every problem the automation’s inputs schema found in the run input (at most 20 either way), each naming the field and the reason; `error` repeats the first one
              items:
                type: object
                required:
                - path
                - message
                properties:
                  path:
                    type: string
                    description: The field, dotted for nesting (`address.city`, `contacts.2.email`); empty for a problem with the body as a whole
                  message:
                    type: string
            scope:
              type: string
              enum:
              - user
              - team
              - project
              - org
              - apiKey
              description: 'For BUDGET_EXCEEDED, whose cap is reached: the key holder’s own (`user`), one of their teams’ (`team`), that of the project the work belongs to (`project`), the organization’s (`org`) or this API key’s (`apiKey`)'
            period:
              type: string
              enum:
              - daily
              - weekly
              - monthly
              description: For BUDGET_EXCEEDED, what the cap counts over — a calendar day, ISO week or calendar month in UTC
            limitCode:
              type: string
              enum:
              - TOKEN_LIMIT
              - COST_LIMIT
              - REQUEST_LIMIT
              description: 'For BUDGET_EXCEEDED, which cap is reached: tokens, cost in cents, or requests'
            used:
              type: number
              description: For BUDGET_EXCEEDED, the usage the cap measured this period, in its unit (tokens, cents or requests)
            limit:
              type: number
              description: For BUDGET_EXCEEDED, the cap, in the same unit
            resetsAt:
              type: number
              description: For BUDGET_EXCEEDED, when the period resets, in epoch milliseconds — `Retry-After` names the same wait in whole seconds
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An organization API key. Create one in Settings → API. Pasted into the explorer on /docs it stays in the page’s memory only and is forgotten on reload — it is never stored.