openapi: 3.2.0
info:
  title: Tale Platform Contacts 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: Contacts
  description: Contact records.
paths:
  /api/v1/contacts:
    get:
      tags:
      - Contacts
      summary: List contacts
      description: Most recently updated first; trashed contacts are hidden. Ordered by `updatedAt`, then `id`, both descending; the cursor is that pair, so a contact updated (or created) while you page — an inbound conversation touching it, a colleague’s edit — moves ahead of the cursor and is not served again in that pass. A full reconciliation re-runs the pass until two consecutive passes agree, or compares `updatedAt` per record. Filters combine with AND; `source` is the closed set the write side takes, any other value answers 400 `INVALID_QUERY`.
      operationId: listContacts
      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: cursor
        in: query
        required: false
        schema:
          type: string
        description: The previous page’s `continueCursor`, unchanged — opaque; omit for the first page. A value this list did not answer is refused with 400 `INVALID_CURSOR` rather than read as the first page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 25
        description: Page size, 1..200 (default 25; out-of-range numbers are clamped, a value that is not a number answers 400 `INVALID_LIMIT`)
      - name: source
        in: query
        required: false
        schema:
          type: string
          enum:
          - manual_import
          - file_upload
          - api_import
          - conversation
          - shopify
          - woocommerce
          - magento
          - bigcommerce
          - prestashop
          - chargebee
          - stripe
          - recurly
          - salesforce
          - hubspot
          - pipedrive
          - zoho
          - sap
          - oracle
          - netsuite
          - mailchimp
          - klaviyo
          - sendgrid
          - webhook
          - zapier
          - custom
        description: Only contacts from this source — the closed set the write side takes; any other value answers 400 `INVALID_QUERY` naming the set (it used to answer an empty page)
      - 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:
        '200':
          description: Paginated contacts
          content:
            application/json:
              schema:
                type: object
                x-tale-pagination: keyset
                required:
                - page
                - isDone
                - continueCursor
                properties:
                  page:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  isDone:
                    type: boolean
                  continueCursor:
                    type: string
                    description: Pass back as `cursor` for the next page; empty when `isDone`
          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'
    post:
      tags:
      - Contacts
      summary: Create contact
      description: '`source` defaults to `api_import`.'
      operationId: createContact
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInput'
      responses:
        '201':
          description: Created — the contact’s id
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                properties:
                  id:
                    type: string
          headers:
            Location:
              $ref: '#/components/headers/Location'
            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'
        '409':
          description: Duplicate email (`CONTACT_DUPLICATE_EMAIL`) or external id (`CONTACT_DUPLICATE_EXTERNAL_ID`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '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/contacts/bulk:
    post:
      tags:
      - Contacts
      summary: Create contacts in bulk
      description: 'Up to 500 contacts per call, each carrying at least one of name, email or externalId (a blank email reads as none); the per-row duplicate check keys on email and externalId. Rows are created independently: the result counts successes and failures and names each failed row with its reason — a row the schema refuses (a malformed email, an unknown key, a missing identity) fails ALONE, reported under `errors[]` as `INVALID_BODY` with its field-named `issues`, while every valid row lands; only the batch’s own shape — the `contacts` array, 1..500 rows, no other top-level key — answers 400 `INVALID_BODY` for the whole call. The body may run to 8 MiB — this operation’s own cap; past it the answer is 413 `BODY_TOO_LARGE`.'
      operationId: bulkCreateContacts
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contacts
              additionalProperties: false
              properties:
                contacts:
                  type: array
                  minItems: 1
                  maxItems: 500
                  description: At least one row — an empty batch is a 400 `INVALID_BODY`, never a 201 that created nothing
                  items:
                    $ref: '#/components/schemas/ContactInput'
      responses:
        '201':
          description: Bulk creation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCreateResult'
          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: '`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 8 MiB — this operation’s own cap, above the door’s 1 MiB default, sized for 500 contacts with 10,000-character notes (`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/contacts/{id}/restore:
    post:
      tags:
      - Contacts
      summary: Restore a contact from the trash
      operationId: restoreContact
      description: 'Puts a trashed contact back in the directory — the remedy a frozen conversation mirror’s 409 `CONVERSATION_CONTACT_TRASHED` names — under the create’s own rule: a live contact that has since taken its email or external id refuses the restore with 409 `CONTACT_DUPLICATE_EMAIL` or `CONTACT_DUPLICATE_EXTERNAL_ID`, so a restore never mints a twin. A contact not in the trash is a no-op that answers the contact; one that does not exist answers 404 `CONTACT_NOT_FOUND`. Its mirrored conversations resume with it — a content snapshot at a higher version applies again. Takes no body.'
      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: Contact ID
      - 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:
        '200':
          description: The contact, live again (or still live)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '400':
          description: A body that is not empty JSON — this operation takes none (`INVALID_BODY`)
          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: Contact not found (`CONTACT_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'
        '409':
          description: A live contact took the email (`CONTACT_DUPLICATE_EMAIL`) or the external id (`CONTACT_DUPLICATE_EXTERNAL_ID`) meanwhile
          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'
  /api/v1/contacts/{id}:
    get:
      tags:
      - Contacts
      summary: Get contact
      operationId: getContact
      description: One contact by id; a contact in the trash or in another organization answers 404 `CONTACT_NOT_FOUND`.
      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: Contact ID
      - 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:
        '200':
          description: The contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
          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: Contact 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'
    patch:
      tags:
      - Contacts
      summary: Update contact
      description: 'Optionally send expectedUpdatedAt from the last contact read. The update locks and checks that revision atomically; a stale revision returns 409 CONTACT_STALE without changing any field. A patch that changes nothing — an empty body, or every field already at its value — writes nothing and leaves `updatedAt` alone (the document rule), so it never spends another client’s `expectedUpdatedAt`; a write that changes something advances `updatedAt`, even within one millisecond. Omit the precondition for the existing unconditional behavior. A changed `externalId` carries through to the conversations mirrored onto this contact: their receipts name the new id and a snapshot naming it applies, while the old id names no live contact and is refused (409 `CONVERSATION_CONTACT_CONFLICT`).'
      operationId: patchContact
      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: Contact ID
      - 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}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactPatch'
      responses:
        '200':
          description: The updated contact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '400':
          description: A body the schema refuses (`INVALID_BODY`), or a patch that would clear the last of `name`, `email` and `externalId` (`CONTACT_IDENTITY_REQUIRED`)
          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: Contact not found (`CONTACT_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'
        '409':
          description: Duplicate email (`CONTACT_DUPLICATE_EMAIL`) or external id (`CONTACT_DUPLICATE_EXTERNAL_ID`), or a stale `expectedUpdatedAt` (`CONTACT_STALE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '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'
    delete:
      tags:
      - Contacts
      summary: Delete contact
      operationId: deleteContact
      description: 'Move the contact to the trash, which frees its email and external id for a new contact; a contact already there answers 404 `CONTACT_NOT_FOUND`. Any mirrored conversation still linked to this contact keeps its messages but stops accepting content snapshots — `POST /api/v1/conversations/sync` answers 409 `CONVERSATION_CONTACT_TRASHED` for it, and its `GET` receipt reports `contactStatus: "trashed"` — until the contact is restored (`POST /api/v1/contacts/{id}/restore`, or the app’s Trash); a `deleted` teardown closes such a mirror but does not reopen it. Because the external id is freed, it is never re-resolved for an existing conversation, so a contact recreated under the same id never inherits the old one’s history.'
      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: Contact ID
      - 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: Deleted
          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: '`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: Contact 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:
  schemas:
    BulkCreateResult:
      type: object
      required:
      - success
      - failed
      - created
      - errors
      description: A body the schema refuses fails the whole call with 400; a row the directory refuses (a duplicate email or external id) fails that row alone and is listed under `errors` with its code. `created` here is the list of rows that landed — unlike the boolean `created` a folder or task result carries.
      properties:
        success:
          type: integer
        failed:
          type: integer
        created:
          type: array
          description: The rows that landed, by input index
          items:
            type: object
            required:
            - index
            - id
            properties:
              index:
                type: integer
              id:
                type: string
        errors:
          type: array
          description: Every row that did not land, by input index — a row the schema refused (`INVALID_BODY`, with its `issues`) beside a row the directory refused (a duplicate); the rest landed regardless.
          items:
            type: object
            required:
            - index
            - error
            - errorCode
            - contact
            properties:
              index:
                type: integer
              error:
                type: string
              errorCode:
                type: string
                enum:
                - INVALID_BODY
                - CONTACT_DUPLICATE_EMAIL
                - CONTACT_DUPLICATE_EXTERNAL_ID
                - CONTACT_CREATE_FAILED
                - unknown
                description: '`INVALID_BODY` — the row failed the schema (`issues` names each field); the `CONTACT_*` codes are the single create’s own refusals.'
              issues:
                type: array
                description: 'Present on an `INVALID_BODY` row: the field-named problems, paths relative to the row (`email`, not `contacts.3.email`).'
                items:
                  type: object
                  required:
                  - path
                  - message
                  properties:
                    path:
                      type: string
                    message:
                      type: string
              contact:
                type: object
                additionalProperties: true
                description: The row as sent — a refused row is echoed whatever shape it had.
    Contact:
      type: object
      required:
      - id
      - organizationId
      - source
      - tags
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        organizationId:
          type: string
        name:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
          format: email
        phone:
          type:
          - string
          - 'null'
        externalId:
          type:
          - string
          - 'null'
        source:
          type: string
        locale:
          type:
          - string
          - 'null'
        address:
          type:
          - object
          - 'null'
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        metadata:
          type:
          - object
          - 'null'
          additionalProperties: true
        notes:
          type:
          - string
          - 'null'
        lifecycleStatus:
          type:
          - string
          - 'null'
          readOnly: true
          description: 'Read-only, set by the platform: null while the contact is live, `expired` once the organization’s retention policy has marked it for purge (such a contact still answers reads until the purge runs), `trashed` after a delete — a trashed contact is not served at all. No input schema takes it; a CRM pipeline stage belongs in `metadata`.'
        createdAt:
          type: integer
          minimum: 0
          description: Epoch milliseconds
        updatedAt:
          type: integer
          minimum: 0
          description: Epoch milliseconds
    ContactInput:
      type: object
      description: Unknown keys are refused (`INVALID_BODY`). Strings are trimmed, and a blank optional field — or one sent as `null` — reads as left out (a CSV-shaped row or a JSON export imports cleanly); the same body clears the field on a PATCH. A create needs at least one of `name`, `email` or `externalId` to file the contact under.
      additionalProperties: false
      properties:
        name:
          type:
          - string
          - 'null'
          maxLength: 300
          description: Trimmed
        email:
          type:
          - string
          - 'null'
          format: email
          maxLength: 320
          description: Trimmed and stored lowercase — a duplicate matches case-insensitively; the part before `@` is at most 64 characters
        phone:
          type:
          - string
          - 'null'
          maxLength: 50
          description: Trimmed — digits and phone punctuation only (`+`, spaces, dashes, parentheses, dots); at least one digit
        source:
          type: string
          enum:
          - manual_import
          - file_upload
          - api_import
          - conversation
          - shopify
          - woocommerce
          - magento
          - bigcommerce
          - prestashop
          - chargebee
          - stripe
          - recurly
          - salesforce
          - hubspot
          - pipedrive
          - zoho
          - sap
          - oracle
          - netsuite
          - mailchimp
          - klaviyo
          - sendgrid
          - webhook
          - zapier
          - custom
          description: Where the contact came from — one of the platform’s data sources; defaults to `api_import`, and `custom` is the catch-all for anything not listed
        locale:
          type:
          - string
          - 'null'
          maxLength: 20
          description: Trimmed
        address:
          type:
          - object
          - 'null'
          additionalProperties: true
          maxProperties: 500
          description: Free-form. On PATCH it is REPLACED whole — an address is a unit. At most 64 KiB of JSON, 8 levels of nesting and 500 keys in total (every nested object counted); a larger value answers 400 `INVALID_BODY` naming the path.
        externalId:
          oneOf:
          - type:
            - string
            - 'null'
            maxLength: 256
          - type:
            - integer
            - 'null'
            minimum: -9007199254740991
            maximum: 9007199254740991
          description: 'Stored as a trimmed string. Send a source system’s id as a string: a number beyond 2^53 − 1 cannot be carried exactly and is refused'
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
            maxLength: 60
            description: Trimmed
          maxItems: 50
        metadata:
          type:
          - object
          - 'null'
          additionalProperties: true
          maxProperties: 500
          description: Free-form. On PATCH it MERGES per RFC 7396 — sent keys are set, omitted keys stay, a key sent as `null` is removed, and the whole field sent as `null` clears it. At most 64 KiB of JSON, 8 levels of nesting and 500 keys in total (every nested object counted); a larger value answers 400 `INVALID_BODY` naming the path.
        notes:
          type:
          - string
          - 'null'
          maxLength: 10000
          description: Trimmed
    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
    ContactPatch:
      type: object
      description: 'Every field optional. `null` clears any optional field, and a blank string reads as `null`; `metadata` merges per RFC 7396 while `address` is replaced whole. A patch may not clear the last of `name`, `email` and `externalId` (400 `CONTACT_IDENTITY_REQUIRED`). Send `expectedUpdatedAt` from the last contact read to update only that revision: a stale one answers 409 `CONTACT_STALE` without changing any field.'
      additionalProperties: false
      properties:
        name:
          type:
          - string
          - 'null'
          maxLength: 300
          description: Trimmed
        email:
          type:
          - string
          - 'null'
          format: email
          maxLength: 320
          description: Trimmed and stored lowercase — a duplicate matches case-insensitively; the part before `@` is at most 64 characters
        phone:
          type:
          - string
          - 'null'
          maxLength: 50
          description: Trimmed — digits and phone punctuation only (`+`, spaces, dashes, parentheses, dots); at least one digit
        source:
          type: string
          enum:
          - manual_import
          - file_upload
          - api_import
          - conversation
          - shopify
          - woocommerce
          - magento
          - bigcommerce
          - prestashop
          - chargebee
          - stripe
          - recurly
          - salesforce
          - hubspot
          - pipedrive
          - zoho
          - sap
          - oracle
          - netsuite
          - mailchimp
          - klaviyo
          - sendgrid
          - webhook
          - zapier
          - custom
          description: Where the contact came from — one of the platform’s data sources; defaults to `api_import`, and `custom` is the catch-all for anything not listed
        locale:
          type:
          - string
          - 'null'
          maxLength: 20
          description: Trimmed
        address:
          type:
          - object
          - 'null'
          additionalProperties: true
          maxProperties: 500
          description: Free-form. On PATCH it is REPLACED whole — an address is a unit. At most 64 KiB of JSON, 8 levels of nesting and 500 keys in total (every nested object counted); a larger value answers 400 `INVALID_BODY` naming the path.
        externalId:
          oneOf:
          - type:
            - string
            - 'null'
            maxLength: 256
          - type:
            - integer
            - 'null'
            minimum: -9007199254740991
            maximum: 9007199254740991
          description: 'Stored as a trimmed string. Send a source system’s id as a string: a number beyond 2^53 − 1 cannot be carried exactly and is refused'
        tags:
          type:
          - array
          - 'null'
          items:
            type: string
            maxLength: 60
            description: Trimmed
          maxItems: 50
        metadata:
          type:
          - object
          - 'null'
          additionalProperties: true
          maxProperties: 500
          description: Free-form. On PATCH it MERGES per RFC 7396 — sent keys are set, omitted keys stay, a key sent as `null` is removed, and the whole field sent as `null` clears it. At most 64 KiB of JSON, 8 levels of nesting and 500 keys in total (every nested object counted); a larger value answers 400 `INVALID_BODY` naming the path.
        notes:
          type:
          - string
          - 'null'
          maxLength: 10000
          description: Trimmed
        expectedUpdatedAt:
          type: integer
          minimum: 0
          maximum: 8640000000000000
          description: The `updatedAt` of the revision this update is based on
  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
    Location:
      description: The created resource’s own path, relative to the request URL — follow it with GET whatever shape the 201 body has
      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
  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.