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

# Chat Completions

> Compatibility endpoint for OpenAI Chat Completions clients. Uses the same Cloud stack, billing, and trace runtime as /v1/responses.

`POST /v1/chat/completions` is the compatibility endpoint for clients that still use OpenAI Chat Completions.

It uses the same Cloud auth, stack resolution, routing, billing, fallback, verification, and trace runtime as `/v1/responses`.

## Recommended request

```json theme={null}
{
  "model": "astrolabe/coding",
  "messages": [
    {
      "role": "user",
      "content": "Explain this build failure in one paragraph."
    }
  ],
  "metadata": {
    "astrolabe": {
      "stack": "code-agent",
      "quality": "high",
      "fallback": true
    }
  }
}
```

## Prefer Responses for new clients

Use `/v1/responses` for new integrations when your client supports it. Keep Chat Completions for existing libraries and compatibility paths.


## OpenAPI

````yaml POST /v1/chat/completions
openapi: 3.1.0
info:
  title: Astrolabe Cloud Gateway API
  version: 1.0.0
  description: >-
    Hosted OpenAI-compatible gateway for Astrolabe Cloud routing stacks, prepaid
    billing, model selection, and route traces.
servers:
  - url: https://api.astrolabe.run
    description: Astrolabe Cloud gateway
security:
  - bearerAuth: []
  - apiKeyAuth: []
paths:
  /v1/chat/completions:
    post:
      summary: Create a chat completion
      description: >-
        Compatibility endpoint for OpenAI Chat Completions clients. Uses the
        same Cloud stack, billing, and trace runtime as /v1/responses.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              default:
                value:
                  model: astrolabe/coding
                  messages:
                    - role: user
                      content: Explain this error.
                  metadata:
                    astrolabe:
                      stack: code-agent
                      quality: high
      responses:
        '200':
          description: Successful JSON or streaming response.
          headers:
            x-astrolabe-cloud-request-id:
              $ref: '#/components/headers/CloudRequestId'
            x-astrolabe-cloud-workspace:
              $ref: '#/components/headers/WorkspaceId'
            x-astrolabe-cloud-key:
              $ref: '#/components/headers/KeyPrefix'
            x-ratelimit-limit:
              $ref: '#/components/headers/RateLimitLimit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/RateLimitReset'
            x-astrolabe-model:
              $ref: '#/components/headers/SelectedModel'
            x-astrolabe-stack-name:
              $ref: '#/components/headers/StackName'
            x-astrolabe-stack-version:
              $ref: '#/components/headers/StackVersion'
            x-astrolabe-policy-status:
              $ref: '#/components/headers/PolicyStatus'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '502':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - messages
      properties:
        model:
          type: string
          default: astrolabe/auto
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        tool_choice: {}
        response_format: {}
        metadata:
          $ref: '#/components/schemas/GatewayMetadata'
      additionalProperties: true
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          additionalProperties: true
        astrolabe:
          type: object
          additionalProperties: true
      additionalProperties: true
    ChatMessage:
      type: object
      properties:
        role:
          type: string
        content: {}
      required:
        - role
        - content
      additionalProperties: true
    GatewayMetadata:
      type: object
      properties:
        astrolabe:
          $ref: '#/components/schemas/AstrolabeMetadata'
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
            details: {}
          required:
            - code
            - message
          additionalProperties: true
      required:
        - error
      additionalProperties: true
    AstrolabeMetadata:
      type: object
      properties:
        stack:
          type: string
        quality:
          type: string
          enum:
            - draft
            - standard
            - high
            - critical
        cost_mode:
          type: string
          enum:
            - lowest_passable
            - balanced
            - fastest_passable
            - premium
            - fixed
        latency_slo_ms:
          type: integer
        verification:
          type: string
          enum:
            - 'off'
            - auto
            - light
            - strict
            - strong
        fallback:
          type: boolean
        explain:
          type: boolean
      additionalProperties: true
  headers:
    CloudRequestId:
      description: Astrolabe Cloud request id for trace lookup and support.
      schema:
        type: string
    WorkspaceId:
      description: Workspace id associated with the API key.
      schema:
        type: string
    KeyPrefix:
      description: Non-secret API key prefix.
      schema:
        type: string
    RateLimitLimit:
      description: Request limit for the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Remaining requests in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Rate-limit reset timestamp.
      schema:
        type: string
    SelectedModel:
      description: Concrete serving model selected by Astrolabe.
      schema:
        type: string
    StackName:
      description: Routing stack name used for this request.
      schema:
        type: string
    StackVersion:
      description: Routing stack version used for this request.
      schema:
        type: string
    PolicyStatus:
      description: Routing stack policy result.
      schema:
        type: string
        enum:
          - passed
          - blocked
          - not_evaluated
  responses:
    Error:
      description: Gateway error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Astrolabe Cloud API key
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````