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

# Responses

Pass-through to the OpenAI Responses API. Request and response bodies follow the standard OpenAI Responses schema. The gateway infers the provider from the model name.

## Headers

<ParamField header="X-Toolken-Key" type="string" required>
  Your Toolken API key. Validated by the gateway and stripped before forwarding.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Your provider key in Bearer format (BYOK), e.g. `Bearer sk-...`. Forwarded untouched, never stored.
</ParamField>

<ParamField header="X-Toolken-Metadata" type="string">
  Primary attribution channel. JSON object of key-value pairs (e.g. `{"agent":"research-agent","customer_id":"cust_abc"}`). Each key becomes a groupable dimension in the dashboard.
</ParamField>

<ParamField header="X-Toolken-Metadata-*" type="string">
  Flat-header shorthand. `X-Toolken-Metadata-Agent: research-agent` writes metadata key `agent`. Equivalent to sending the same key in `X-Toolken-Metadata`.
</ParamField>

<ParamField header="X-Toolken-Metadata-Feature" type="string">
  Sets the `feature` metadata key. Use to group costs by agent name, workflow, UI surface, or job type.
</ParamField>

<ParamField header="X-Toolken-Metadata-Customer-Id" type="string">
  Sets the `customer_id` metadata key. Use to attribute costs to an end-customer, org slug, or account ID.
</ParamField>

## Body

<ParamField body="model" type="string" required>
  Model identifier for the OpenAI Responses API (e.g. `gpt-4o`).
</ParamField>

<ParamField body="input" type="string or array" required>
  Input text or structured input array. Follows the standard OpenAI Responses schema.
</ParamField>

<ParamField body="stream" type="boolean">
  If true, the gateway streams Server-Sent Events back from the provider.
</ParamField>

## Response

<ResponseField name="id" type="string">Unique response ID.</ResponseField>
<ResponseField name="object" type="string">Object type identifier.</ResponseField>
<ResponseField name="output" type="array">The generated output. Shape depends on the model and input type.</ResponseField>
<ResponseField name="usage" type="object">Token usage counts. Shape follows the standard OpenAI Responses API.</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://gateway.toolken.ai/v1/responses \
    -H "X-Toolken-Key: tk_live_..." \
    -H "Authorization: Bearer sk-..." \
    -H "Content-Type: application/json" \
    -d '{"model": "gpt-4o", "input": "What is the capital of France?"}'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://gateway.toolken.ai/v1",
      api_key="sk-...",
      default_headers={"X-Toolken-Key": "tk_live_..."},
  )
  client.responses.create(
      model="gpt-4o",
      input="What is the capital of France?",
  )
  ```

  ```javascript Node theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://gateway.toolken.ai/v1",
    apiKey: "sk-...",
    defaultHeaders: { "X-Toolken-Key": "tk_live_..." },
  });
  await client.responses.create({
    model: "gpt-4o",
    input: "What is the capital of France?",
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "resp_abc123",
    "object": "response",
    "output": [
      {
        "type": "message",
        "role": "assistant",
        "content": [{ "type": "output_text", "text": "The capital of France is Paris." }]
      }
    ],
    "usage": {
      "input_tokens": 9,
      "output_tokens": 8,
      "total_tokens": 17
    }
  }
  ```
</ResponseExample>