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

# Create chat completion

> Route a prompt to the best model and return an OpenAI-compatible completion enriched with a prysm block.

<Note>
  **POST** `https://api.prysm1.com/v1/chat/completions` · Requires authentication
</Note>

The main endpoint. Send OpenAI-shaped messages with `model: "auto"` and PRYSM
[routes](/concepts/routing) the request to the best-value model, returning a standard
completion plus a [`prysm`](#response) block.

## Authorization

<ParamField header="Authorization" type="string" required>
  Your secret key as a bearer token: `Bearer prysm_sk_...`
</ParamField>

## Body

<ParamField body="messages" type="object[]" required>
  The conversation so far. Each message has a `role` (`system`, `user`, or `assistant`)
  and `content` (string).
</ParamField>

<ParamField body="model" type="string" default="auto">
  `"auto"` to let PRYSM choose, or any [catalog model ID](/models) to pin the request to
  a specific model. Unknown IDs fall back to a safe budget default.
</ParamField>

<ParamField body="max_tokens" type="integer" default="1000">
  Maximum number of tokens to generate in the completion.
</ParamField>

<ParamField body="temperature" type="number" default="0.7">
  Sampling temperature between 0 and 2. Lower is more deterministic.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Reserved for streaming responses.
</ParamField>

<ParamField body="routing_mode" type="string">
  Force a routing mode: `quality`, `balanced`, or `agility`. Omit to let PRYSM choose.
  PRYSM-specific.
</ParamField>

<ParamField body="brain_config" type="object">
  An inline [BRAIN.md](/concepts/brain-md) config (normalized object) to apply to this
  request — rules, `max_cost`, `blocked`, `fallback`, and more. PRYSM-specific.
</ParamField>

## Response

Returns an OpenAI-compatible [chat completion object](https://platform.openai.com/docs/api-reference/chat/object)
with an added `prysm` block.

<ResponseField name="id" type="string">
  Unique completion ID, prefixed `prysm-`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `chat.completion`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp (seconds) when the completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The catalog ID of the model that actually ran.
</ResponseField>

<ResponseField name="choices" type="object[]">
  The generated choices.

  <Expandable title="choice">
    <ResponseField name="index" type="integer">Position in the list.</ResponseField>

    <ResponseField name="message" type="object">
      The assistant message: `{ "role": "assistant", "content": "..." }`.
    </ResponseField>

    <ResponseField name="finish_reason" type="string">Why generation stopped, e.g. `stop`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Token accounting: `prompt_tokens`, `completion_tokens`, `total_tokens`.
</ResponseField>

<ResponseField name="prysm" type="object">
  The PRYSM extension block — routing decision, cost, latency, and proof.

  <Expandable title="prysm">
    <ResponseField name="routing" type="object">
      <Expandable title="routing">
        <ResponseField name="mode" type="string">`quality`, `balanced`, `agility`, or `direct`.</ResponseField>
        <ResponseField name="model_display" type="string">Human-readable model name.</ResponseField>
        <ResponseField name="provider" type="string">Upstream provider that served the call.</ResponseField>
        <ResponseField name="reason" type="string">Why this model was chosen.</ResponseField>
        <ResponseField name="tier" type="string">`budget`, `mid`, `premium`, or `frontier`.</ResponseField>
        <ResponseField name="signals_detected" type="object">Intent signals detected in the prompt.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cost" type="object">
      <Expandable title="cost">
        <ResponseField name="input_usd" type="number">Cost of input tokens, USD.</ResponseField>
        <ResponseField name="output_usd" type="number">Cost of output tokens, USD.</ResponseField>
        <ResponseField name="total_usd" type="number">Total request cost, USD.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="latency_ms" type="integer">End-to-end latency in milliseconds.</ResponseField>

    <ResponseField name="proof" type="object">
      The [PrysmProof](/concepts/prysmproof) receipt: `request_id`, `timestamp`,
      `proof_hash`, `model`, `provider`, `mode`, `reason`, `verifiable`.
    </ResponseField>

    <ResponseField name="fallback" type="boolean">
      `true` if the intended model was unavailable and a fallback served the call.
    </ResponseField>

    <ResponseField name="fallback_from" type="string | null">Intended model, if a fallback occurred.</ResponseField>
    <ResponseField name="fallback_to" type="string | null">Model that actually served the call, if a fallback occurred.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```python Python theme={null}
  from prysm import Prysm

  client = Prysm()
  resp = client.chat.completions.create(
      model="auto",
      messages=[{"role": "user", "content": "Write a Python quicksort"}],
  )
  print(resp.choices[0].message.content)
  ```

  ```typescript Node theme={null}
  import { Prysm } from "@prysmai/sdk";

  const client = new Prysm();
  const resp = await client.chat.completions.create({
    model: "auto",
    messages: [{ role: "user", content: "Write a TypeScript quicksort" }],
  });
  console.log(resp.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.prysm1.com/v1/chat/completions \
    -H "Authorization: Bearer $PRYSM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "auto",
      "messages": [{ "role": "user", "content": "Write a Python quicksort" }]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "prysm-a1b2c3d4",
    "object": "chat.completion",
    "created": 1748888641,
    "model": "deepseek-v4-flash",
    "choices": [
      {
        "index": 0,
        "message": { "role": "assistant", "content": "def quicksort(a): ..." },
        "finish_reason": "stop"
      }
    ],
    "usage": { "prompt_tokens": 18, "completion_tokens": 240, "total_tokens": 258 },
    "prysm": {
      "routing": {
        "mode": "balanced",
        "model_display": "DeepSeek V4 Flash",
        "provider": "deepseek",
        "reason": "Code: 95% cheaper than GPT-5.2",
        "tier": "budget",
        "signals_detected": { "code": true }
      },
      "cost": { "input_usd": 0.00000504, "output_usd": 0.0001008, "total_usd": 0.00010584 },
      "latency_ms": 740,
      "proof": {
        "request_id": "b1e7c0d2-3f4a-5b6c-7d8e-9f0a1b2c3d4e",
        "timestamp": "2026-06-02T18:24:01.123456+00:00",
        "proof_hash": "sha256:a1b2c3d4e5f6a7b8",
        "model": "DeepSeek V4 Flash",
        "provider": "deepseek",
        "mode": "balanced",
        "reason": "Code: 95% cheaper than GPT-5.2",
        "verifiable": true
      },
      "fallback": false,
      "fallback_from": null,
      "fallback_to": null
    }
  }
  ```
</ResponseExample>