> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List conversation messages using JWE payload

> POST form of `GET` on this path. It accepts the same parameters as a flat JSON
body (`ConversationHistoryQueryBody`) instead of a query string, and returns the same response.
Use it when the request parameters must be encrypted. See "Sending parameters
in a POST body" and "Payload encryption" in the API description.

- Request encryption off: send `ConversationHistoryQueryBody` as `application/json`.
- Request encryption on: send the same object encrypted as an
  `EncryptedRequest`, preferably as `application/jose+json`.
- Response encryption on: every response except `401` is an
  `EncryptedResponse` with `X-ABL-Encrypted: true`.


Retrieve conversation messages while sending the request parameters in the request body instead of the URL query string. It supports the same filters, pagination options, and response format as [the corresponding GET endpoint](/agent-platform/api-reference/analytics-list-conversation-messages).

Use the POST endpoint when the request parameters **must be encrypted**. When request encryption is enabled for the Platform Key, send the request parameters as a JSON Web Encryption (JWE) payload. The encrypted payload protects the parameters that would otherwise be exposed in the GET query string.

Request encryption is configured on the Platform Key in Studio. The request uses a flattened JWE in JSON serialization and is encrypted using the AES-256 key associated with the Platform Key.

If response encryption is also enabled for the Platform Key, the endpoint returns encrypted responses, including error responses, except for `401 Unauthorized` responses. The response is a JWE encrypted for the RSA public key configured on the Platform Key.


## OpenAPI

````yaml agent-platform/api-specs/messages.yaml post /api/public/analytics/projects/{projectId}/conversation-history
openapi: 3.1.0
info:
  title: ABL Public Analytics Messages API
  version: 1.0.0
  summary: Retrieve project-scoped conversation messages.
  description: >
    Returns the messages exchanged in a project's conversations, in order.
    Message

    content is filtered according to the project's PII policy before it is
    returned, so

    sensitive values may be masked or removed.


    Give either a date range (`fromDate` and `toDate` together) or a list of

    `sessionIds`.


    For paging, prefer `cursor`: pass the `nextCursor` value from the previous
    response.

    `offset` also works, and `skip` is an older name for `offset` that is still

    accepted. Use only one of the three in a single request.


    Authenticate with the `x-api-key` header. The key must be bound to the
    project you

    are querying and have `analytics:read` permission.


    ## Sending parameters in a POST body


    Every GET on this API has a POST form on the same path. Send the same
    parameters

    as a flat JSON object instead of a query string. Use POST when the
    parameters

    themselves must be encrypted: a GET query string is never encrypted. GET
    stays

    available and unchanged.


    - Body keys are exactly the GET query parameter names. Numbers and booleans
    are
      converted to the strings the GET parser expects. List parameters accept a
      JSON array or a comma-separated string.
      `traceDimensions` is an object of dimension name to value, for example
      `{"traceDimensions": {"accountTier": "gold"}}`, instead of the
      `traceDimensions[key]` query form.
    - An unknown key, a `null`, or a nested value is rejected with
      `400 INVALID_QUERY_PARAMETER`. A body that is not a JSON object is rejected
      with `400 INVALID_REQUEST_BODY`.
    - Do not add a query string to a POST (`400 INVALID_QUERY_PARAMETER`), and
    do
      not split parameters between the query string and the body.
    - `Content-Type` must be `application/json` or `application/jose+json`,
      otherwise `415 UNSUPPORTED_MEDIA_TYPE`.
    - Permissions, validation, pagination and the response shape are identical
    to
      the GET form.

    ## Payload encryption


    Payload encryption is an opt-in setting on a Platform Key, configured in
    Studio

    under Settings → API Keys → Platform Keys. It has two independent toggles.

    Neither changes what the key may access, and both are available only to keys

    bound to exactly one project.


    **Request encryption** applies to POST bodies (a GET has no body). The body
    must

    be a JWE (RFC 7516) in flattened JSON serialization, `{protected, iv,

    ciphertext, tag}`, whose protected header is
    `{"alg":"dir","enc":"A256GCM"}`,

    optionally with `kid`, `typ` and `cty`. The key is the 32-byte AES-256
    request

    key Studio shows when request encryption is enabled. `kid` is optional; if
    sent

    it must equal the key's Key ID shown in Studio.


    **Response encryption** applies to every response sent after the key is

    authenticated, successes and errors alike (400, 403, 404, 413, 415, 429,
    500,

    503). The body is a flattened JWE `{protected, encrypted_key, iv,
    ciphertext,

    tag}` with protected header

    `{"alg":"RSA-OAEP-256","enc":"A256GCM","kid":"<Key
    ID>","pkf":"<fingerprint>"}`,

    sealed with a fresh AES-256 key per response that is wrapped with the RSA
    public

    key (≥ 2048 bits) configured on the Platform Key. `pkf` is the SHA-256 hex

    digest of that public key's SubjectPublicKeyInfo DER. The response keeps

    `Content-Type: application/json` and adds `X-ABL-Encrypted: true`.
    Decrypting

    it yields exactly the JSON documented in this spec. A `401` is never
    encrypted

    (the key is not known yet), and a `304` has no body.


    | Key setting | Plain JSON body | JWE body |

    |---|---|---|

    | Request encryption off | accepted | `400 ENCRYPTED_PAYLOAD_INVALID` |

    | Request encryption on | `400 ENCRYPTED_PAYLOAD_INVALID` | decrypted, then
    handled as plain JSON |


    Encryption fails closed: a configured key never receives plaintext by
    accident.


    - `400 ENCRYPTED_PAYLOAD_INVALID` is returned for every envelope problem:
    any
      other `alg`/`enc`, `zip` or `crit`, unknown header parameters, `unprotected`,
      `header`, `aad` or `recipients` members, a `kid` that is not this key's,
      padded or standard base64, a wrong IV (12 bytes) or tag (16 bytes) length, a
      failed authentication tag, or a plaintext that is not JSON.
    - `503 ENCRYPTION_CONFIG_UNAVAILABLE` (with `Retry-After: 30`) means the
    key's
      encryption configuration could not be read. Retry later; there is no
      plaintext fallback.
    - `500 INTERNAL_ERROR` with a content-free body is returned if a response
    cannot
      be encrypted.

    All JWE members are unpadded base64url. The AAD is the ASCII of the
    `protected`

    member, as in standard JWE, so JOSE libraries (for example `jose` for
    Node.js)

    can produce and open these envelopes directly. Pin the algorithms when

    decrypting: key management `RSA-OAEP-256`, content encryption `A256GCM`.
  x-source-release: develop
  x-source-commit: b6a1a328b3e089e03ca2494a7091d72a6a481d4b
  x-payload-encryption:
    jira: ABLP-5317
    source: develop, PR
    source-commit: 6de86f59eb
    runtime-capability: 'GET /health -> capabilities.payloadEncryption: 2'
servers:
  - url: https://{host}
    variables:
      host:
        default: runtime.example.com
security:
  - ApiKeyAuth: []
tags:
  - name: Messages
paths:
  /api/public/analytics/projects/{projectId}/conversation-history:
    post:
      tags:
        - Messages
      summary: List conversation messages (parameters in the body)
      description: >
        POST form of `GET` on this path. It accepts the same parameters as a
        flat JSON

        body (`ConversationHistoryQueryBody`) instead of a query string, and
        returns the same response.

        Use it when the request parameters must be encrypted. See "Sending
        parameters

        in a POST body" and "Payload encryption" in the API description.


        - Request encryption off: send `ConversationHistoryQueryBody` as
        `application/json`.

        - Request encryption on: send the same object encrypted as an
          `EncryptedRequest`, preferably as `application/jose+json`.
        - Response encryption on: every response except `401` is an
          `EncryptedResponse` with `X-ABL-Encrypted: true`.
      operationId: queryPublicAnalyticsMessages
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/ConversationHistoryQueryBody'
                - $ref: '#/components/schemas/EncryptedRequest'
            examples:
              plain:
                summary: Request encryption off
                value:
                  fromDate: '2026-08-01T00:00:00.000Z'
                  toDate: '2026-08-02T00:00:00.000Z'
                  sessionIds:
                    - sess-01J4S8Y1
                  direction: asc
                  limit: 50
              encrypted:
                summary: Request encryption on (JWE of the plain example)
                value:
                  protected: >-
                    eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2In0
                  iv: cWTRqrpaghnMMupa
                  ciphertext: >-
                    XS6t52iwj0dyyLSO8MSNNs5adCSkQwoThj41rgB411aaXCcsFHbxTX90CJVVKv0e-zhbZB6Nu-yfLdPuOCgmLGqyz7fRWygIlmykQxOtZe8U3mlAwMeLOZjvVoxhxlwCkvfFVrwQK9VcD0ulkrl7S7n8uw8sPYH7av6c-SYgzyCayFdVkg3T8vAPqB4meMDj
                  tag: fB3zJcDCZngejDbljVlrFw
          application/jose+json:
            schema:
              $ref: '#/components/schemas/EncryptedRequest'
            example:
              protected: >-
                eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2In0
              iv: cWTRqrpaghnMMupa
              ciphertext: >-
                XS6t52iwj0dyyLSO8MSNNs5adCSkQwoThj41rgB411aaXCcsFHbxTX90CJVVKv0e-zhbZB6Nu-yfLdPuOCgmLGqyz7fRWygIlmykQxOtZe8U3mlAwMeLOZjvVoxhxlwCkvfFVrwQK9VcD0ulkrl7S7n8uw8sPYH7av6c-SYgzyCayFdVkg3T8vAPqB4meMDj
              tag: fB3zJcDCZngejDbljVlrFw
      responses:
        '200':
          description: Message page returned successfully (same body as the GET form).
          headers:
            Cache-Control:
              schema:
                type: string
              example: private, no-store, max-age=0
            X-ABL-Encrypted:
              $ref: '#/components/headers/XAblEncrypted'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/MessageListResponse'
                  - $ref: '#/components/schemas/EncryptedResponse'
              examples:
                encrypted:
                  summary: >-
                    Response for a key with response encryption on (decrypt to
                    get the plain body)
                  value:
                    protected: >-
                      eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIiwia2lkIjoiNjZmN2ExYzJlNGIwYTFkMmMzZTRmNWE2IiwicGtmIjoiOGE0ZDEzYjAzOGY5ZmNiYWU4N2E1ZGE1MzAxYzJjYmU1MTdmOTgxNGE4MmU1MzRiNmU1MTAwYzMzYzM1ZmI4MyJ9
                    encrypted_key: >-
                      cxwYB_RTEFVDJx8aTcMp8TLQH6o01QMHAzNA7mYjuER1qs_JASJffXFTH5mPPRxzf603WuTjZ2vQg0pO5r9NwoylzJHxikpc1eogSaIPRFZiIPVqWIWe5BruacS7vxmmMngq5VZotnr3HYril7nmOghHz-BHtbZnDwHnJqqsOp4beEj-53Ix5gW_Dw2wZMFCR9UGU2qKAfNQxHjz_D7LobQMVLh52PpBmgJDMvWhmFnVsDZcOQnF2TdD9rD0siewsm0u8tvFTP4VGNdRhS1mX_IbkHzWK_iE_36Kb6YVpIl8wjQO9J9JCjZRwo8mirXdUBpXpbwLELLEkEb3IpQMAA
                    iv: hYMp9LBIqja7h4Da
                    ciphertext: cc6swtjMe1Gt4NLVChIqmw
                    tag: LGS-Aivh61DvyK6k1MHsCg
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/ResponseTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
        minLength: 1
  schemas:
    ConversationHistoryQueryBody:
      type: object
      additionalProperties: false
      description: >
        POST form of the GET query parameters: a flat JSON object whose keys are
        the

        GET query parameter names. For a Platform Key with request encryption
        on, send

        this object encrypted as an `EncryptedRequest` instead.
      properties:
        fromDate:
          description: Same as the `fromDate` query parameter of the GET operation.
          type: string
          format: date-time
        toDate:
          description: Same as the `toDate` query parameter of the GET operation.
          type: string
          format: date-time
        sessionIds:
          description: >-
            Same as the `sessionIds` query parameter of the GET operation. Send
            a JSON array, or a comma-separated string as in the query string.
          anyOf:
            - type: array
              maxItems: 10000
              uniqueItems: true
              items:
                type: string
                minLength: 1
            - type: string
              minLength: 1
        callerNumber:
          description: >
            Same as the `callerNumber` query parameter of the GET operation.
            Send a JSON

            array of caller values in any provider format (no URL encoding
            needed), or a

            comma-separated string. Every entry must be a string with at least
            one letter

            or digit and at most 512 characters; an empty array returns 400.
          example:
            - +91 98765 43210
            - Anonymous
          anyOf:
            - type: array
              minItems: 1
              maxItems: 100
              items:
                type: string
                minLength: 1
                maxLength: 512
            - type: string
              minLength: 1
        channelUIds:
          description: >-
            Same as the `channelUIds` query parameter of the GET operation. Send
            a JSON array, or a comma-separated string as in the query string.
          anyOf:
            - type: array
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                minLength: 1
            - type: string
              minLength: 1
        channel:
          description: >-
            Same as the `channel` query parameter of the GET operation. Send a
            JSON array, or a comma-separated string as in the query string.
          anyOf:
            - type: array
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                enum:
                  - http_async
                  - slack
                  - line
                  - msteams
                  - whatsapp
                  - messenger
                  - instagram
                  - twilio_sms
                  - zendesk
                  - telegram
                  - genesys
                  - genesys_open_messaging
                  - ai4w
                  - kore_agent_assist
                  - email
                  - voice_vxml
                  - korevg
                  - audiocodes
                  - genesys_audio_connector
                  - voice_pipeline
                  - voice_realtime
                  - voice
                  - voice_twilio
                  - voice_livekit
                  - ag_ui
                  - a2a
                  - sdk_websocket
                  - web_debug
                  - web_chat
                  - api
                  - http
            - type: string
              minLength: 1
        environment:
          description: >-
            Same as the `environment` query parameter of the GET operation. Send
            a JSON array, or a comma-separated string as in the query string.
          anyOf:
            - type: array
              maxItems: 100
              uniqueItems: true
              items:
                type: string
                enum:
                  - dev
                  - staging
                  - production
                  - working-copy
            - type: string
              minLength: 1
        traceDimensions:
          type: object
          description: >
            Same filter as the `traceDimensions[key]` query parameter, as an
            object of

            dimension name to value. Values may be strings, numbers, booleans,
            or an array

            of those. Nested objects are rejected.
          additionalProperties:
            anyOf:
              - type: string
              - type: number
              - type: boolean
              - type: array
                items:
                  type:
                    - string
                    - number
                    - boolean
        cursor:
          description: Same as the `cursor` query parameter of the GET operation.
          type: string
          minLength: 1
        offset:
          description: Same as the `offset` query parameter of the GET operation.
          type: integer
          minimum: 0
          default: 0
        skip:
          description: Same as the `skip` query parameter of the GET operation.
          type: integer
          minimum: 0
        limit:
          description: Same as the `limit` query parameter of the GET operation.
          type: integer
          minimum: 1
          maximum: 10000
          default: 100
        direction:
          description: Same as the `direction` query parameter of the GET operation.
          type: string
          enum:
            - asc
            - desc
          default: asc
    EncryptedRequest:
      type: object
      additionalProperties: false
      required:
        - protected
        - iv
        - ciphertext
        - tag
      description: >
        Request body for a Platform Key with request encryption on: a JWE in
        flattened

        JSON serialization (RFC 7516 §7.2.2). The plaintext is the JSON body
        documented

        for the plain POST form. Send with `Content-Type: application/jose+json`
        or

        `application/json`.
      properties:
        protected:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: >
            base64url of the protected header JSON. Decodes to
            `RequestProtectedHeader`.

            Its ASCII is also the AES-GCM additional authenticated data.
        encrypted_key:
          type: string
          maxLength: 0
          description: 'Empty or omitted: `dir` has no wrapped key.'
        iv:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of a fresh random 12-byte AES-GCM IV.
        ciphertext:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the AES-256-GCM ciphertext.
        tag:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the 16-byte AES-GCM authentication tag.
    MessageListResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - totalRecords
        - hasMore
        - offset
        - limit
        - messages
        - nextCursor
      properties:
        success:
          type: boolean
          const: true
          description: |
            Always true on a successful response.
        totalRecords:
          type: integer
          minimum: 0
          description: |
            Total number of messages matching your filters, across all pages.
        hasMore:
          type: boolean
          description: |
            Whether more pages are available after this one.
        offset:
          type: integer
          minimum: 0
          description: |
            The offset applied to this response.
        limit:
          type: integer
          minimum: 1
          maximum: 10000
          description: |
            The page size applied to this response.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: |
            The messages on this page.
        nextCursor:
          type:
            - string
            - 'null'
          description: Opaque cursor for the next page.
    EncryptedResponse:
      type: object
      additionalProperties: false
      required:
        - protected
        - encrypted_key
        - iv
        - ciphertext
        - tag
      description: >
        Response body for a Platform Key with response encryption on (signalled
        by the

        `X-ABL-Encrypted: true` header): a JWE in flattened JSON serialization.
        The

        decrypted plaintext is the JSON body documented for that status code.
      properties:
        protected:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: >-
            base64url of the protected header. Decodes to
            `ResponseProtectedHeader`.
        encrypted_key:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: >-
            The per-response AES-256 key, wrapped with the customer's RSA public
            key using RSA-OAEP-256.
        iv:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the 12-byte AES-GCM IV (fresh per response).
        ciphertext:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the AES-256-GCM ciphertext.
        tag:
          type: string
          pattern: ^[A-Za-z0-9_-]+$
          description: base64url of the 16-byte AES-GCM authentication tag.
    Message:
      type: object
      additionalProperties: false
      required:
        - id
        - sessionId
        - type
        - role
        - content
        - channel
        - sourceChannel
        - environment
        - channelUId
        - traceDimensions
        - traceId
        - attachmentIds
        - hasPII
        - metadata
        - sequence
        - messageOrder
        - orderingVersion
        - agentName
        - timestamp
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: |
            The message identifier.
        sessionId:
          type: string
          description: |
            The conversation this message belongs to.
        type:
          type: string
          enum:
            - incoming
            - outgoing
            - system
            - tool
          description: >
            Direction of the message: `incoming` from the end user, `outgoing`
            to the end user,

            `system` for platform messages, `tool` for tool output.
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - tool
          description: |
            Who the message is attributed to, in the usual chat sense.
        content:
          type: string
          description: |
            The message text, after the project PII policy has been applied.
        channel:
          type: string
          description: Stored session channel, matched exactly by the `channel` filter.
          enum:
            - ''
            - http_async
            - slack
            - line
            - msteams
            - whatsapp
            - messenger
            - instagram
            - twilio_sms
            - zendesk
            - telegram
            - genesys
            - genesys_open_messaging
            - ai4w
            - kore_agent_assist
            - email
            - voice_vxml
            - korevg
            - audiocodes
            - genesys_audio_connector
            - voice_pipeline
            - voice_realtime
            - voice
            - voice_twilio
            - voice_livekit
            - ag_ui
            - a2a
            - sdk_websocket
            - web_debug
            - web_chat
            - api
            - http
        sourceChannel:
          type: string
          description: >
            The channel this individual message came in on. This can differ from
            the

            session's `channel` if the conversation moved between channels
            part-way

            through.
          enum:
            - ''
            - http_async
            - slack
            - line
            - msteams
            - whatsapp
            - messenger
            - instagram
            - twilio_sms
            - zendesk
            - telegram
            - genesys
            - genesys_open_messaging
            - ai4w
            - kore_agent_assist
            - email
            - voice_vxml
            - korevg
            - audiocodes
            - genesys_audio_connector
            - voice_pipeline
            - voice_realtime
            - voice
            - voice_twilio
            - voice_livekit
            - ag_ui
            - a2a
            - sdk_websocket
            - web_debug
            - web_chat
            - api
            - http
        environment:
          description: |
            The environment the conversation ran in. Null when not recorded.
          type:
            - string
            - 'null'
          enum:
            - dev
            - staging
            - production
            - working-copy
            - null
        channelUId:
          type:
            - string
            - 'null'
          description: Resolved end-user identity for the channel session.
        traceDimensions:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: |
            Custom dimensions recorded against the session, as key/value pairs.
        traceId:
          type:
            - string
            - 'null'
          description: >
            The trace covering how this message was produced. Use it with the
            traces endpoint.
        attachmentIds:
          type: array
          items:
            type: string
          description: |
            Identifiers of any files attached to the message.
        hasPII:
          type: boolean
          description: >
            Whether personal information was detected in this message. When
            true, the content you

            see may be masked.
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Sanitized message metadata. Assistant messages include normalized
            response provenance.
          properties:
            isLlmGenerated:
              type: boolean
              description: >
                Whether this message was generated by a model rather than
                scripted.
            responseProvenance:
              $ref: '#/components/schemas/ResponseProvenance'
        sequence:
          type:
            - number
            - 'null'
          minimum: 0
          description: |
            Position of the message within its session, starting at 1.
        messageOrder:
          type:
            - number
            - 'null'
          description: >
            Durable ordering position recorded when the message was written.
            Null for

            messages stored before durable ordering was recorded.
        orderingVersion:
          type: number
          minimum: 1
          description: >
            Version of the ordering scheme behind `messageOrder`. `1` when no
            version was

            recorded.
        agentName:
          type:
            - string
            - 'null'
          description: |
            The agent that produced this message. Null for user messages.
        timestamp:
          type: string
          format: date-time
          description: |
            When the message was sent.
        createdAt:
          type: string
          format: date-time
          description: |
            When the message record was created.
        updatedAt:
          type: string
          format: date-time
          description: |
            When the message record was last changed.
    ErrorEnvelope:
      type: object
      required:
        - error
      properties:
        success:
          type: boolean
          const: false
          description: |
            Always false on an error response.
        error:
          description: >
            Details of what went wrong. `code` is a stable machine-readable
            value; `message` is

            human-readable.
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        message:
          type: string
          description: >-
            Present on some authorization denials in addition to
            `error.message`.
        required:
          description: >-
            Permission(s) the caller was missing. Present on authorization
            denials.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
    ResponseProvenance:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - kind
        - disclaimerRequired
        - usedLlmInternally
      properties:
        schemaVersion:
          type: integer
          const: 1
          description: Version of this provenance metadata contract.
        kind:
          type: string
          enum:
            - scripted
            - llm
            - mixed
          description: >-
            `scripted` for authored output, `llm` for model-generated output, or
            `mixed` when both contributed.
        disclaimerRequired:
          type: boolean
          description: True when the customer-visible response was LLM-generated.
        usedLlmInternally:
          type: boolean
          description: Whether an LLM contributed internally
          including to scripted final output.: null
  headers:
    XAblEncrypted:
      description: >-
        Present with value `true` when the body is an `EncryptedResponse`.
        Absent otherwise.
      schema:
        type: string
        enum:
          - 'true'
  responses:
    BadRequest:
      description: >
        The request could not be understood. Common causes: an invalid or
        one-sided date

        range, neither a date range nor `sessionIds` supplied, more than one of

        `cursor`, `offset`, and `skip` used together, too many filter values, or
        a

        date-range query that would span more than 10,000 sessions. The
        `error.code`

        says which.


        Encryption and POST-body errors also return 400:
        `ENCRYPTED_PAYLOAD_INVALID`

        (malformed, unexpected or undecryptable JWE, or a plain body for a

        request-encrypted key), `INVALID_REQUEST_BODY` (POST body is not a JSON
        object),

        and `INVALID_QUERY_PARAMETER` (unknown, null or nested POST body key, or
        a query

        string on a POST).


        `INVALID_CALLER_NUMBER`: the `callerNumber` parameter is present but an
        entry is

        empty or has no letter or digit after cleanup (an empty value, only
        separators,

        a trailing or doubled comma, only whitespace, invisible characters or

        punctuation such as `+`, or an empty POST array), is not a string, or is
        longer

        than 512 characters. Any caller format, including bare

        digits and national formats, is accepted. The message names the position
        of

        the offending entry and never echoes it.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    Unauthorized:
      description: Missing or invalid `x-api-key`, or Authorization was supplied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: >
        The key lacks `analytics:read` for its bound project, or
        (`CALLER_NUMBER_LOOKUP_DISABLED`)

        the request used `callerNumber` while the project's reporting exposure
        config

        disables the `identity` field group.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    NotFound:
      description: Project not found or concealed because it is outside the key's scope.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    ResponseTooLarge:
      description: A single rendered message cannot fit within the 1 MiB response budget.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    UnsupportedMediaType:
      description: >-
        A POST body was sent with a `Content-Type` other than `application/json`
        or `application/jose+json` (`UNSUPPORTED_MEDIA_TYPE`).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    RateLimited:
      description: Tenant request rate limit exceeded.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    InternalError:
      description: >
        Unexpected conversation-history failure.


        Also returned, with a content-free body, when a response cannot be
        encrypted for

        a response-encrypted key.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
    Unavailable:
      description: >
        Conversation-history or trace-dimension backing store unavailable.


        `ENCRYPTION_CONFIG_UNAVAILABLE` (with `Retry-After: 30`) means the
        Platform

        Key's payload-encryption configuration could not be read. There is no
        plaintext

        fallback.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/EncryptedResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Project-bound API key. Do not send an Authorization header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.