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

# Completions (legacy)

> Raw-prompt text completion, the pre-chat OpenAI shape, served for tooling that still speaks it.

Unlike [chat completions](/docs/reference/chat-completions.md), the `prompt` string is handed to the model as-is, no chat template, no roles, no system prompt. The model simply continues your text. Streaming works the same way as on the chat endpoint.

> [!NOTE]
>
> The models in the catalog are instruction-tuned, and their quality comes from their chat formatting, prefer **chat completions** for anything conversational, and keep this endpoint for continuation-style tasks or legacy integrations that require the `prompt`/`text` shape.


## OpenAPI

````yaml /openapi/inference.yaml post /completions
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:
  /completions:
    post:
      summary: Completions (legacy)
      description: >-
        Raw-prompt text completion, the pre-chat OpenAI shape, served for
        tooling that still speaks it.
      operationId: createCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompletionRequest'
            example:
              model: zai-org/GLM-5.3
              prompt: 'The three laws of robotics are:'
              max_tokens: 200
              temperature: 0.7
      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/Completion'
              examples:
                completion:
                  summary: Completion
                  value:
                    id: cmpl-…
                    object: text_completion
                    created: 1785229039
                    model: zai-org/GLM-5.3
                    choices:
                      - index: 0
                        text: ' 1. A robot may not injure …'
                        finish_reason: stop
                    usage:
                      prompt_tokens: 9
                      completion_tokens: 74
                      total_tokens: 83
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-sent events with `choices[0].text` deltas, terminated
                  by `data: [DONE]`.
              examples:
                stream:
                  summary: Stream (payloads elided)
                  value: |-
                    data: …

                    data: …

                    data: [DONE]
        '400':
          $ref: '#/components/responses/CompletionsBadRequest'
        '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/completions \
              -H "Authorization: Bearer $PEARL_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "zai-org/GLM-5.3",
                "prompt": "The three laws of robotics are:",
                "max_tokens": 200,
                "temperature": 0.7
              }'
components:
  schemas:
    CreateCompletionRequest:
      type: object
      required:
        - model
        - prompt
      properties:
        model:
          type: string
          description: A catalog model ID from `GET /models`.
        prompt:
          type: string
          description: Raw text the model continues.
        max_tokens:
          type: integer
          description: Cap on generated tokens.
        temperature:
          type: number
          description: >-
            Sampling parameter; behaves as on [chat
            completions](/reference/chat-completions).
        top_p:
          type: number
          description: >-
            Sampling parameter; behaves as on [chat
            completions](/reference/chat-completions).
        frequency_penalty:
          type: number
          description: >-
            Sampling parameter; behaves as on [chat
            completions](/reference/chat-completions).
        presence_penalty:
          type: number
          description: >-
            Sampling parameter; behaves as on [chat
            completions](/reference/chat-completions).
        stop:
          type: array
          description: >-
            Sampling parameter; behaves as on [chat
            completions](/reference/chat-completions).
          items:
            type: string
        seed:
          type: integer
          description: >-
            Sampling parameter; behaves as on [chat
            completions](/reference/chat-completions).
        top_k:
          type: integer
          description: >-
            Sampling parameter extension; behaves as on [chat
            completions](/reference/chat-completions).
        min_p:
          type: number
          description: >-
            Sampling parameter extension; behaves as on [chat
            completions](/reference/chat-completions).
        'n':
          type: integer
          minimum: 1
          maximum: 8
          default: 1
          description: Number of choices to generate, 1 to 8. Defaults to 1.
        stream:
          type: boolean
          description: >-
            Server-sent events with `choices[0].text` deltas, terminated by
            `data: [DONE]`.
    Completion:
      type: object
      properties:
        id:
          type: string
          description: Completion ID.
        object:
          type: string
          enum:
            - text_completion
          description: Always `text_completion`.
        created:
          type: integer
          description: Unix timestamp (seconds).
        model:
          type: string
          description: The model that served the request.
        choices:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
                description: The generated continuation of `prompt`.
              finish_reason:
                type: string
                enum:
                  - stop
                  - length
                description: >-
                  `stop` (natural end or stop sequence) or `length` (hit
                  `max_tokens`).
        usage:
          type: object
          description: >-
            `prompt_tokens`, `completion_tokens`, `total_tokens`, what you're
            billed on.
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
    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:
    CompletionsBadRequest:
      description: 'Invalid request: malformed JSON, or a missing or wrongly typed field.'
      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.