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

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# Create a chat completion

> OpenAI's Chat Completions API. `model` is `ambral/auto` with an `x-workload` header (or `ambral/auto:<workload>`), which serves the workload's primary model and records the call to its traces. The answer is in Chat Completions' own response schema, with `id` the call's own id, `model` the model that served it, and `usage.cost` what the call costs, in USD; any other key the provider adds is removed. With `stream: true` the answer is server-sent events, one chunk each, ending with `data: [DONE]`. A failure after the 200 is a chunk whose `error` says what failed, or the error envelope when Ambral couldn't read the provider's event, and a provider whose connection drops ends the stream without `[DONE]`. Otherwise it is one JSON completion, or the error envelope when Ambral couldn't read it. An error the provider answers reaches the client with the provider's status, in the same error envelope. Every top-level key Chat Completions names, and the provider's own extension keys, are passed through as they were sent; any other key is left out. A request Ambral must price and can't is a 400: one that would let the provider choose another model, or run a tool or add-on Ambral doesn't price.



## OpenAPI

````yaml /api-reference/gateway.json post /v1/chat/completions
openapi: 3.1.0
info:
  title: Ambral Gateway API
  version: '1'
servers:
  - url: https://api.ambral.ai
security: []
tags:
  - name: inference
    description: OpenAI's Chat Completions API, and the models it lists
  - name: messages
    description: Anthropic's Messages API
paths:
  /v1/chat/completions:
    post:
      tags:
        - inference
      summary: Create a chat completion
      description: >-
        OpenAI's Chat Completions API. `model` is `ambral/auto` with an
        `x-workload` header (or `ambral/auto:<workload>`), which serves the
        workload's primary model and records the call to its traces. The answer
        is in Chat Completions' own response schema, with `id` the call's own
        id, `model` the model that served it, and `usage.cost` what the call
        costs, in USD; any other key the provider adds is removed. With `stream:
        true` the answer is server-sent events, one chunk each, ending with
        `data: [DONE]`. A failure after the 200 is a chunk whose `error` says
        what failed, or the error envelope when Ambral couldn't read the
        provider's event, and a provider whose connection drops ends the stream
        without `[DONE]`. Otherwise it is one JSON completion, or the error
        envelope when Ambral couldn't read it. An error the provider answers
        reaches the client with the provider's status, in the same error
        envelope. Every top-level key Chat Completions names, and the provider's
        own extension keys, are passed through as they were sent; any other key
        is left out. A request Ambral must price and can't is a 400: one that
        would let the provider choose another model, or run a tool or add-on
        Ambral doesn't price.
      operationId: inference.chatCompletions
      parameters:
        - name: x-workload
          in: header
          schema:
            allOf:
              - $ref: '#/components/schemas/WorkloadName'
              - description: >-
                  The workload the request is for, which `ambral/auto` serves
                  from its primary model and whose traces record it. A model
                  suffix (`ambral/auto:<workload>`) names it too, and the two
                  must agree. A request that names none and carries the
                  `x-ambral-eval` header is for its eval's workload.
          required: false
        - name: x-ambral-upstream
          in: header
          schema:
            allOf:
              - $ref: '#/components/schemas/UpstreamId'
              - description: >-
                  The upstream that serves the request, at that upstream's
                  price, for debugging. Otherwise Ambral chooses. A model it
                  doesn't serve is a 400.
          required: false
        - name: x-ambral-eval
          in: header
          schema:
            $ref: '#/components/schemas/EvalHeaderEncoded'
          required: false
        - name: x-session-id
          in: header
          schema:
            allOf:
              - $ref: '#/components/schemas/SessionId'
              - description: >-
                  The session the request belongs to: the same id on every
                  request of a session, 8–128 characters of A-Z a-z 0-9 _ -; any
                  other value is ignored. The body's `session_id` or an
                  `x-<vendor>-session-id` header names it too. Without one, each
                  request is a session.
          required: false
        - name: x-ambral-end-user
          in: header
          schema:
            allOf:
              - $ref: '#/components/schemas/EndUserId'
              - description: >-
                  Your own id for the person the request serves, recorded on its
                  session's trace: 1–128 characters of A-Z a-z 0-9 . _ : @ + -;
                  any other value is ignored. Without it, the body's
                  `safety_identifier`, `user` or `metadata.user_id` names them.
                  A session keeps the first one it is sent.
          required: false
        - name: x-ambral-labels
          in: header
          schema:
            type: string
            allOf:
              - description: >-
                  Labels on the request's session, `key=value` or a bare `tag`,
                  comma-separated: up to 16. A key is lowercase letters, digits,
                  `.`, `_` and `-`, starting with a letter or digit, at most 63
                  characters. A value is letters, digits, spaces and `. _ : / @
                  + -`, at most 128 characters; spaces around it are dropped. A
                  session's labels gather every request's, a later value
                  replacing an earlier one's; once a session holds 16, a later
                  request's new keys are dropped. Invalid labels are ignored,
                  all of them, and the response says why in its own
                  `x-ambral-labels` header.
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionsChatCompletionRequest'
        required: true
      responses:
        '200':
          description: 'The provider''s answer: one completion, or a stream of chunks.'
          content:
            application/json:
              schema:
                description: >-
                  The completion, or the error envelope when Ambral couldn't
                  read the provider's answer.
                anyOf:
                  - $ref: '#/components/schemas/ChatCompletionsChatCompletion'
                  - $ref: '#/components/schemas/ChatCompletionsErrorBody'
            text/event-stream:
              schema:
                description: >-
                  Server-sent events, each event's `data` as JSON: a chunk, or
                  the error envelope when Ambral couldn't read the provider's
                  event. A chunk whose `error` is set says what failed. The
                  stream ends with `data: [DONE]`, unless the provider's
                  connection dropped, which ends it without one.
                anyOf:
                  - $ref: '#/components/schemas/ChatCompletionsChatCompletionChunk'
                  - $ref: '#/components/schemas/ChatCompletionsErrorBody'
          headers:
            x-ambral-route:
              schema:
                type: string
                enum:
                  - routed
                allOf:
                  - description: '`routed`: `ambral/auto` chose the model.'
              required: true
            x-ambral-model:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ModelId'
                  - description: The model that served the request.
              required: true
            x-ambral-workload:
              schema:
                allOf:
                  - $ref: '#/components/schemas/WorkloadName'
                  - description: The workload the request was served and recorded for.
              required: true
            x-ambral-upstream:
              schema:
                allOf:
                  - $ref: '#/components/schemas/UpstreamId'
                  - description: >-
                      The upstream that served the request, only when
                      `x-ambral-upstream` pinned it.
              required: false
            x-ambral-recording:
              schema:
                type: string
                allOf:
                  - description: >-
                      `skipped; reason=<reason>` when the request named a
                      workload but wasn't recorded, with `<reason>` one of
                      `unsupported_tools`.
              required: false
            x-session-id:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SessionId'
                  - description: >-
                      The session Ambral made for a request that named none:
                      send it back on the session's next request.
              required: false
            x-ambral-labels:
              schema:
                type: string
                enum:
                  - ignored; reason=too_many
                  - ignored; reason=invalid_key
                  - ignored; reason=invalid_value
                allOf:
                  - description: >-
                      `ignored; reason=<reason>` when the request's
                      `x-ambral-labels` header was ignored: the request was
                      served and recorded without its labels. `too_many` names
                      more than 16 labels, `invalid_key` a key that isn't a
                      label key, and `invalid_value` a value that isn't a label
                      value.
              required: false
        '400':
          description: >-
            The request is invalid: its body, a header, the workload or upstream
            it names, or a model other than `ambral/auto`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
        '401':
          description: >-
            No inference key, or one that is unknown or revoked, or whose org
            isn't active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
        '402':
          description: No available credit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
        '404':
          description: No workload has the name the request gives.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
        '429':
          description: The provider is limiting the rate of requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
        '502':
          description: The provider couldn't be reached. Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
        '503':
          description: >-
            The key, or the route of the workload the request names, couldn't be
            read. Retry the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
        default:
          description: >-
            An error the provider answered, with the provider's status, in the
            same error envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsErrorBody'
      security:
        - bearer: []
components:
  schemas:
    WorkloadName:
      type: string
    UpstreamId:
      type: string
      minLength: 1
    EvalHeaderEncoded:
      type: string
      description: >-
        `<run>; workload=<workload>; model=<model>`: the request is a call of an
        eval run, which Ambral's SDKs set. A request that names no workload (no
        `x-workload`, no model suffix) is for the run's. A request for the run's
        workload is served the run's model, one of the workload's pool, and a
        request for another workload that workload's primary. Either way it is
        recorded as an eval trace of the run, never as production. It needs a
        session, and a value that doesn't parse is a 400.
    SessionId:
      type: string
    EndUserId:
      type: string
      description: >-
        1 to 128 letters, digits, and `. _ : @ + -`: the customer's own id for
        the person served.
    ChatCompletionsChatCompletionRequest:
      type: object
      properties:
        model:
          $ref: '#/components/schemas/ModelName'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionsMessage'
        tools:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionsTool'
            - type: 'null'
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
        session_id:
          description: >-
            The session the request belongs to, as the `x-session-id` header
            names it; a value that isn't a valid session id is ignored.
        provider:
          description: >-
            A routing preference: which providers may serve the request, where
            several could.
        cache_control:
          description: A cache breakpoint after the whole prompt.
      required:
        - model
        - messages
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsChatCompletion:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ChatCompletionsCompletionId'
        object:
          type: string
        created:
          $ref: '#/components/schemas/EpochSeconds'
        model:
          $ref: '#/components/schemas/ModelName'
        system_fingerprint:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsSystemFingerprint'
            - type: 'null'
        service_tier:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsServiceTier'
            - type: 'null'
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionsChoice'
        usage:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsUsage'
            - type: 'null'
      required:
        - id
        - model
        - choices
      additionalProperties: false
    ChatCompletionsErrorBody:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ChatCompletionsErrorDetail'
      required:
        - error
      additionalProperties: false
    ChatCompletionsChatCompletionChunk:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ChatCompletionsCompletionId'
        object:
          type: string
        created:
          $ref: '#/components/schemas/EpochSeconds'
        model:
          $ref: '#/components/schemas/ModelName'
        system_fingerprint:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsSystemFingerprint'
            - type: 'null'
        service_tier:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsServiceTier'
            - type: 'null'
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionsChunkChoice'
        usage:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsUsage'
            - type: 'null'
        error:
          $ref: '#/components/schemas/ChatCompletionsErrorDetail'
      required:
        - id
        - model
        - choices
      additionalProperties: false
    ModelId:
      type: string
      minLength: 1
      maxLength: 256
    ModelName:
      type: string
      minLength: 1
      maxLength: 256
    ChatCompletionsMessage:
      type: object
      properties:
        role:
          type: string
        content:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsContent'
            - type: 'null'
        tool_calls:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionsToolCall'
            - type: 'null'
        tool_call_id:
          $ref: '#/components/schemas/ChatCompletionsToolCallId'
        cache_control:
          description: A cache breakpoint after the message.
        reasoning:
          description: An answer's reasoning, sent back as text with no signature.
        reasoning_content:
          description: >-
            An answer's reasoning, sent back as text with no signature, under
            the name some SDKs give it.
        reasoning_details:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionsReasoningDetail'
            - type: 'null'
          description: An answer's reasoning, sent back as its details came.
      required:
        - role
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsTool:
      type: object
      properties:
        type:
          type: string
        function:
          $ref: '#/components/schemas/ChatCompletionsFunctionDefinition'
        cache_control:
          description: A cache breakpoint after the tool.
      required:
        - type
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsCompletionId:
      type: string
    EpochSeconds:
      type: integer
      minimum: 0
      maximum: 9007199254740991
    ChatCompletionsSystemFingerprint:
      type: string
    ChatCompletionsServiceTier:
      type: string
    ChatCompletionsChoice:
      type: object
      properties:
        index:
          $ref: '#/components/schemas/ChatCompletionsChoiceIndex'
        message:
          $ref: '#/components/schemas/ChatCompletionsResponseMessage'
        finish_reason:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsFinishReason'
            - type: 'null'
        logprobs:
          anyOf:
            - {}
            - type: 'null'
      required:
        - index
        - message
        - finish_reason
      additionalProperties: false
    ChatCompletionsUsage:
      type: object
      properties:
        prompt_tokens:
          $ref: '#/components/schemas/TokenCount'
        completion_tokens:
          $ref: '#/components/schemas/TokenCount'
        total_tokens:
          $ref: '#/components/schemas/TokenCount'
        prompt_tokens_details:
          anyOf:
            - type: object
              properties:
                cached_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
                cache_write_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
                cache_write_hour_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
                  description: >-
                    How many of `cache_write_tokens` were written to be kept for
                    an hour.
                audio_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
              additionalProperties: false
            - type: 'null'
        completion_tokens_details:
          anyOf:
            - type: object
              properties:
                reasoning_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
                audio_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
                accepted_prediction_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
                rejected_prediction_tokens:
                  anyOf:
                    - $ref: '#/components/schemas/TokenCount'
                    - type: 'null'
              additionalProperties: false
            - type: 'null'
        cost:
          anyOf:
            - $ref: '#/components/schemas/ShownCostUsd'
            - type: 'null'
          description: What the call costs, in USD.
      required:
        - prompt_tokens
        - completion_tokens
      additionalProperties: false
    ChatCompletionsErrorDetail:
      type: object
      properties:
        message:
          type: string
        type:
          $ref: '#/components/schemas/ChatCompletionsErrorType'
        code:
          $ref: '#/components/schemas/ChatCompletionsErrorCode'
      required:
        - message
        - type
        - code
      additionalProperties: false
    ChatCompletionsChunkChoice:
      type: object
      properties:
        index:
          $ref: '#/components/schemas/ChatCompletionsChoiceIndex'
        delta:
          $ref: '#/components/schemas/ChatCompletionsDelta'
        finish_reason:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsFinishReason'
            - type: 'null'
        logprobs:
          anyOf:
            - {}
            - type: 'null'
      required:
        - index
        - delta
      additionalProperties: false
    ChatCompletionsContent:
      anyOf:
        - $ref: '#/components/schemas/ChatCompletionsText'
        - type: array
          items:
            $ref: '#/components/schemas/ChatCompletionsContentPart'
    ChatCompletionsToolCall:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ChatCompletionsToolCallId'
        type:
          type: string
        function:
          $ref: '#/components/schemas/ChatCompletionsFunctionCall'
      required:
        - id
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsToolCallId:
      type: string
    ChatCompletionsReasoningDetail:
      type: object
      properties:
        format:
          description: >-
            Whose reasoning the detail is, which only a model of that kind reads
            back.
        index:
          description: Where a streamed detail's pieces join.
        id:
          description: The detail's id.
        summary:
          description: A summary of the detail's reasoning.
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsFunctionDefinition:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ToolName'
        description:
          $ref: '#/components/schemas/ChatCompletionsToolDescription'
        parameters:
          type: object
        strict:
          anyOf:
            - type: boolean
            - type: 'null'
      required:
        - name
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsChoiceIndex:
      type: integer
      minimum: -9007199254740991
      maximum: 9007199254740991
    ChatCompletionsResponseMessage:
      type: object
      properties:
        role:
          type: string
        content:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsText'
            - type: 'null'
        refusal:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsText'
            - type: 'null'
        tool_calls:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionsToolCall'
            - type: 'null'
        audio:
          anyOf:
            - {}
            - type: 'null'
        annotations:
          anyOf:
            - type: array
            - type: 'null'
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsText'
            - type: 'null'
        reasoning_details:
          anyOf:
            - type: array
            - type: 'null'
      required:
        - role
      additionalProperties: false
    ChatCompletionsFinishReason:
      type: string
    TokenCount:
      type: integer
      minimum: 0
      maximum: 9007199254740991
    ShownCostUsd:
      type: number
    ChatCompletionsErrorType:
      type: string
    ChatCompletionsErrorCode:
      type: string
    ChatCompletionsDelta:
      type: object
      properties:
        role:
          type: string
        content:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsText'
            - type: 'null'
        refusal:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsText'
            - type: 'null'
        tool_calls:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/ChatCompletionsToolCallDelta'
            - type: 'null'
        audio:
          anyOf:
            - {}
            - type: 'null'
        annotations:
          anyOf:
            - type: array
            - type: 'null'
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ChatCompletionsText'
            - type: 'null'
        reasoning_details:
          anyOf:
            - type: array
            - type: 'null'
      additionalProperties: false
    ChatCompletionsText:
      type: string
    ChatCompletionsContentPart:
      type: object
      properties:
        type:
          type: string
        cache_control:
          description: A cache breakpoint after the part.
      required:
        - type
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsFunctionCall:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/ToolName'
        arguments:
          $ref: '#/components/schemas/ChatCompletionsArguments'
      required:
        - name
        - arguments
      allOf:
        - type: object
          additionalProperties: {}
    ToolName:
      type: string
    ChatCompletionsToolDescription:
      type: string
    ChatCompletionsToolCallDelta:
      type: object
      properties:
        index:
          $ref: '#/components/schemas/ChatCompletionsToolCallIndex'
        id:
          $ref: '#/components/schemas/ChatCompletionsToolCallId'
        type:
          type: string
        function:
          type: object
          properties:
            name:
              $ref: '#/components/schemas/ToolName'
            arguments:
              $ref: '#/components/schemas/ChatCompletionsArguments'
          allOf:
            - type: object
              additionalProperties: {}
      required:
        - index
      allOf:
        - type: object
          additionalProperties: {}
    ChatCompletionsArguments:
      type: string
    ChatCompletionsToolCallIndex:
      type: integer
      minimum: -9007199254740991
      maximum: 9007199254740991
  securitySchemes:
    bearer:
      description: An inference key, made on the API keys page of Ambral's app.
      type: http
      scheme: Bearer

````

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