> ## 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.

# Responses

> Primary Astrolabe Cloud inference endpoint. Supports virtual models, concrete model IDs, routing stack selection, streaming, billing, and route traces.

`POST /v1/responses` is the recommended Astrolabe Cloud inference endpoint for new integrations.

It accepts OpenAI-style Responses payloads and adds Cloud routing, billing, stack policy, fallback, verification, and traceability.

## Recommended request

```json theme={null}
{
  "model": "astrolabe/auto",
  "input": "Summarize this support conversation.",
  "metadata": {
    "astrolabe": {
      "stack": "customer-data",
      "quality": "high",
      "verification": "auto"
    }
  }
}
```

## Streaming

Set `stream: true` for server-sent events. Streaming responses still include Cloud request, stack, model, and rate-limit headers.

## Billing

The gateway reserves prepaid balance before provider execution and finalizes the debit from provider usage where available.


## OpenAPI

````yaml POST /v1/responses
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/responses:
    post:
      summary: Create a response
      description: >-
        Primary Astrolabe Cloud inference endpoint. Supports virtual models,
        concrete model IDs, routing stack selection, streaming, billing, and
        route traces.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              default:
                value:
                  model: astrolabe/auto
                  input: Explain routing stacks in one sentence.
              specificStack:
                value:
                  model: astrolabe/auto
                  input: Draft a customer-safe incident update.
                  metadata:
                    astrolabe:
                      stack: customer-data
                      quality: high
                      verification: strong
      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/ResponseResource'
            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:
    ResponsesRequest:
      type: object
      required:
        - input
      properties:
        model:
          type: string
          default: astrolabe/auto
        input: {}
        instructions:
          type: string
        stream:
          type: boolean
          default: false
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        tool_choice: {}
        response_format: {}
        reasoning: {}
        text: {}
        max_output_tokens:
          type: integer
        metadata:
          $ref: '#/components/schemas/GatewayMetadata'
      additionalProperties: true
    ResponseResource:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        status:
          type: string
        model:
          type: string
        output:
          type: array
          items:
            type: object
            additionalProperties: true
        usage:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
      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

````