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

# Responses

> Stateless response creation with native JSON and SSE responses.

## Not supported

Responses are stateless. These return `400`:

* `previous_response_id`, and `item_reference` input items: send the history in `input` instead.
* `store: true` and `background: true`.

There are no endpoints to retrieve, delete, or cancel a stored response, and no WebSocket transport. Disconnecting a request can still incur usage for generated tokens. See the [SDK example](/docs/integrations/openai-responses.md) for a multi-turn loop.

## Reasoning

Set the effort with `"reasoning": {"effort": "high"}`. Levels a model doesn't serve round up to the next one it does, and the response echoes the applied level in `reasoning.effort`. `"effort": "none"` turns thinking off; GLM-5.3 and GLM-5.3-Flash always think and return `400`. `max_output_tokens` covers the reasoning and the answer. See [how effort levels map](/docs/reasoning.md#effort-mapping).


## OpenAPI

````yaml /openapi/inference.yaml post /responses
openapi: 3.1.0
info:
  title: Pearl Inference API
  version: '1.0'
  description: >-
    The data-plane API your applications call to run models: OpenAI- and
    Anthropic-compatible endpoints behind one base URL.
servers:
  - url: https://inference.pearlresearch.ai/v1
security:
  - inferenceKey: []
paths:
  /responses:
    post:
      summary: Responses
      description: Stateless response creation with native JSON and SSE responses.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
            example:
              model: YOUR_MODEL_ID
              input: Hello
              store: false
              max_output_tokens: 8192
      responses:
        '200':
          description: The completion, or an event stream when streaming.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                response:
                  summary: Response
                  value:
                    id: resp_…
                    object: response
                    created_at: 1785229039
                    status: completed
                    model: YOUR_MODEL_ID
                    output:
                      - type: message
                        id: msg_…
                        role: assistant
                        status: completed
                        content:
                          - type: output_text
                            text: Hello! How can I help?
                            annotations: []
                    usage:
                      input_tokens: 9
                      input_tokens_details:
                        cached_tokens: 0
                      output_tokens: 12
                      output_tokens_details:
                        reasoning_tokens: 0
                      total_tokens: 21
            text/event-stream:
              schema:
                type: string
                description: >-
                  With `stream: true` the response is native Responses
                  server-sent events: each one an `event:` line naming its type
                  and a `data:` line with the JSON. A successful stream ends
                  with `response.completed` or `response.incomplete`, whose
                  `response` carries the usage; there is no `[DONE]` sentinel. A
                  failed generation ends with `response.failed`, and an error
                  after the stream has started arrives as an `error` event.
              examples:
                streamError:
                  summary: Error after the stream started
                  value: >-
                    event: error

                    data:
                    {"type":"error","code":"server_error","message":"upstream
                    stream error","param":null}
        '400':
          $ref: '#/components/responses/ResponsesBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/OutOfCredits'
        '403':
          $ref: '#/components/responses/WrongRegion'
        '404':
          $ref: '#/components/responses/ModelNotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '529':
          $ref: '#/components/responses/NoCapacity'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl https://inference.pearlresearch.ai/v1/responses \
              -H "Authorization: Bearer $PEARL_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"model":"YOUR_MODEL_ID","input":"Hello","store":false,"max_output_tokens":8192}'
components:
  schemas:
    CreateResponseRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: >-
            A chat model ID from `GET /models`. A model that doesn't serve
            Responses returns `404`.
        input:
          description: >-
            A string, or an array of input items: messages, plus the output
            items earlier turns returned (reasoning, function calls) and your
            `function_call_output` items. Send the whole history each turn; item
            references are refused.
          oneOf:
            - title: string
              type: string
            - title: array
              type: array
              items:
                type: object
        instructions:
          type: string
          description: A system message for this request.
        max_output_tokens:
          type: integer
          description: Cap on generated tokens, reasoning included.
        stream:
          type: boolean
          description: Stream server-sent events instead of one JSON response.
        store:
          type: boolean
          enum:
            - false
          default: false
          description: >-
            Must be `false` or omitted (omitted is sent as `false`). Responses
            are stateless, so `true` returns `400`.
        reasoning:
          type: object
          description: >-
            `{"effort": …}`, one of `none`, `minimal`, `low`, `medium`, `high`,
            `xhigh`, `max`; see [Reasoning](#reasoning).
          properties:
            effort:
              type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
        tools:
          type: array
          description: Function tools the model may call. Support varies by model.
          items:
            type: object
        temperature:
          type: number
          description: >-
            Sampling parameter, as on [chat
            completions](/reference/chat-completions).
        top_p:
          type: number
          description: >-
            Sampling parameter, as on [chat
            completions](/reference/chat-completions).
    Response:
      type: object
      properties:
        id:
          type: string
          description: Response ID.
        object:
          type: string
          enum:
            - response
          description: Always `response`.
        created_at:
          type: integer
          description: Unix timestamp (seconds).
        status:
          type: string
          enum:
            - completed
            - incomplete
            - cancelled
          description: >-
            `completed`, `incomplete` (stopped early, for example at
            `max_output_tokens`), or `cancelled`. Check it before using
            `output`.
        model:
          type: string
          description: The model that served the request.
        output:
          type: array
          description: >-
            Output items in order: reasoning models add a `reasoning` item, then
            a `message` with `output_text` content, or `function_call` items
            when the model calls tools. Replay them in the next turn's `input`.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - reasoning
                  - message
                  - function_call
        usage:
          type: object
          description: >-
            `input_tokens` and `output_tokens`, what you're billed on, with
            `input_tokens_details.cached_tokens` and
            `output_tokens_details.reasoning_tokens` when the model reports
            them.
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            input_tokens_details:
              type: object
              properties:
                cached_tokens:
                  type: integer
            output_tokens_details:
              type: object
              properties:
                reasoning_tokens:
                  type: integer
        reasoning:
          type: object
          description: >-
            Levels a model doesn't serve round up to the next one it does, and
            the response echoes the applied level in `reasoning.effort`.
          properties:
            effort:
              type: string
    OpenAIError:
      type: object
      description: Errors are JSON in OpenAI's shape, with the request ID in the body.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - rate_limit_error
                - api_error
            code:
              type: string
              description: >-
                Present only when set, for example `model_not_found` or
                `no_capacity`.
            request_id:
              type: string
              description: The request ID.
  headers:
    X-Request-ID:
      description: >-
        The request ID. Send your own UUID in `X-Request-ID` to use it as the
        ID. Include the ID when you contact support.
      schema:
        type: string
      example: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    ResponsesBadRequest:
      description: >-
        Invalid request: malformed JSON, a missing or wrongly typed field, a
        stateful feature (see Not supported), or an unsupported reasoning
        control.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            malformedJson:
              summary: Malformed JSON
              value:
                error:
                  message: malformed JSON
                  type: invalid_request_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    Unauthorized:
      description: >-
        Missing, unknown, revoked, or expired API key, a key over its credit
        limit, or a management key.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            unknownKey:
              summary: Unknown API key
              value:
                error:
                  message: unknown API key
                  type: authentication_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    OutOfCredits:
      description: >-
        Your organization is out of credits. Top up on the
        [Billing](https://platform.pearlresearch.ai/billing) page, then retry.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            outOfCredits:
              summary: Out of credits
              value:
                error:
                  message: your organization is out of credits
                  type: api_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    WrongRegion:
      description: >-
        Wrong endpoint for your organization's [inference
        region](/data-residency).
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            wrongRegion:
              summary: Wrong endpoint for the region
              value:
                error:
                  message: wrong endpoint for your organization's inference region
                  type: permission_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    ModelNotFound:
      description: >-
        Unknown model (code `model_not_found`), or one this endpoint doesn't
        serve.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            unknownModel:
              summary: Unknown model
              value:
                error:
                  message: unknown model
                  type: invalid_request_error
                  code: model_not_found
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    PayloadTooLarge:
      description: Request body over 20 MiB.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            bodyTooLarge:
              summary: Body over 20 MiB
              value:
                error:
                  message: request body over 20 MiB
                  type: invalid_request_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    RateLimited:
      description: >-
        A [rate limit](/plans) for your organization and the model was reached.
        Wait for the `Retry-After` header's seconds.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            rateLimited:
              summary: Rate limit reached
              value:
                error:
                  message: rate limit reached
                  type: rate_limit_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    InternalError:
      description: Internal error. Safe to retry with backoff.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            internalError:
              summary: Internal error
              value:
                error:
                  message: internal error
                  type: api_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    BadGateway:
      description: >-
        The model server failed or returned a malformed response. Retry with
        backoff.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            modelServerFailed:
              summary: Model server failed
              value:
                error:
                  message: the model server failed
                  type: api_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    ServiceUnavailable:
      description: >-
        Temporarily unavailable, for example during a deploy. Retry after the
        `Retry-After` header's seconds.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            unavailable:
              summary: Temporarily unavailable
              value:
                error:
                  message: temporarily unavailable
                  type: api_error
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
    NoCapacity:
      description: >-
        No capacity for the model right now (code `no_capacity`). Retry with
        backoff.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OpenAIError'
          examples:
            noCapacity:
              summary: No capacity
              value:
                error:
                  message: no capacity for the model right now
                  type: api_error
                  code: no_capacity
                  request_id: 6f0b6e0a-6a8f-4c62-9b1e-3d2c1a0f9e87
  securitySchemes:
    inferenceKey:
      type: http
      scheme: bearer
      description: >-
        `Bearer` followed by an inference API key (`sk-prl-infapi-`). Create
        keys on the [API Keys](https://platform.pearlresearch.ai/api-keys) page.
        Management keys (`sk-prl-mgmt-`) cannot call models.

````

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