> For the complete documentation index, see [llms.txt](https://docs.promptshuttle.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.promptshuttle.com/api-reference/openai-compatible.md).

# OpenAI-Compatible Endpoint

PromptShuttle exposes an OpenAI-compatible chat completion endpoint. If you already use the OpenAI SDK, you can switch to PromptShuttle by changing the base URL and API key — no other code changes needed.

## Endpoint

```
POST /api/v1/chat/completions
```

## Request

The request body follows the [OpenAI Chat Completion](https://platform.openai.com/docs/api-reference/chat/create) format with PromptShuttle extensions.

### Required fields

| Field      | Type   | Description                                                        |
| ---------- | ------ | ------------------------------------------------------------------ |
| `model`    | string | Model identifier in `provider/model` format (e.g. `openai/gpt-4o`) |
| `messages` | array  | Array of message objects (see [Messages](#messages) below)         |

### Optional fields

| Field             | Type    | Description                                                                                                        |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `temperature`     | float   | Sampling temperature (0-2). Lower = more deterministic.                                                            |
| `top_p`           | float   | Nucleus sampling threshold.                                                                                        |
| `max_tokens`      | integer | Maximum tokens to generate.                                                                                        |
| `seed`            | integer | Seed for deterministic sampling (provider support varies).                                                         |
| `stream`          | boolean | Enable SSE streaming. Default `false`. See [Streaming](https://docs.promptshuttle.com/api-reference/streaming.md). |
| `stream_options`  | object  | Streaming configuration (see below).                                                                               |
| `tools`           | array   | Tool definitions in OpenAI format.                                                                                 |
| `tool_choice`     | string  | Tool selection mode: `"auto"` (default), `"none"`, `"required"`, or a specific tool.                               |
| `response_format` | object  | Structured output format. Use `{ "type": "json_schema", "json_schema": { ... } }`.                                 |
| `user`            | string  | End-user identifier. Used for per-customer tracking if `X-Shuttle-Customer-Id` header is not set.                  |

### PromptShuttle extensions

These fields are non-standard and specific to PromptShuttle:

| Field         | Type   | Description                                                                                         |
| ------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `x_log_level` | string | Override logging level: `"Trace"`, `"Debug"`, `"Information"`, `"Warning"`, `"Error"`, `"Critical"` |
| `x_nonce`     | string | Opaque cache-bust string. Included in the response-cache hash but never sent to providers.          |

### Custom headers

| Header                     | Description                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| `X-Shuttle-Customer-Id`    | End-customer identifier for per-customer usage attribution.                                  |
| `X-Shuttle-Callback-Url`   | Origin where your app serves its own tools. Required for caller-hosted (relative-URL) tools. |
| `X-Shuttle-Callback-Token` | Secret presented back on caller-hosted tool calls. Held for the run, never stored.           |
| `X-Shuttle-Debug-Url`      | Deprecated alias of `X-Shuttle-Callback-Url`; also attaches a `DebugUrl:` tag.               |

See [Caller-Hosted Tools](https://docs.promptshuttle.com/tools/caller-hosted-tools.md) for how relative tool URLs resolve, and why a missing callback origin fails the call instead of falling back.

## Messages

Each message in the `messages` array has:

| Field     | Type   | Values                              |
| --------- | ------ | ----------------------------------- |
| `role`    | string | `"user"`, `"assistant"`, `"system"` |
| `content` | array  | Array of content parts              |

### Content parts

Each content part has a `type` field:

**Text content:**

```json
{ "type": "text", "text": "Your prompt here" }
```

**Image content (URL):**

```json
{ "type": "image_url", "image_url": { "url": "https://example.com/image.png" } }
```

**Image content (base64 data URL):**

```json
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBOR..." } }
```

Data URLs are automatically parsed into base64 + media type for providers that require it (e.g. Gemini).

## Response

### Synchronous response

```json
{
  "id": "request_id",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}
```

### Streaming response

When `stream: true`, the endpoint returns Server-Sent Events. See [Streaming (SSE)](https://docs.promptshuttle.com/api-reference/streaming.md) for the full event reference.

## Stream options

When streaming, you can configure the event stream:

| Field                   | Type    | Default | Description                                                                                                                                                                             |
| ----------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include_usage`         | boolean | `true`  | Emit periodic `usage.update` events.                                                                                                                                                    |
| `usage_interval_ms`     | integer | `5000`  | Interval between usage updates (milliseconds).                                                                                                                                          |
| `content_deltas`        | boolean | `false` | Send the answer text while the model writes it. See [Answer text](https://docs.promptshuttle.com/api-reference/streaming.md#answer-text). The default is `true` on `/api/v1/inference`. |
| `include_tool_results`  | boolean | `false` | Not available at this time. The server ignores it.                                                                                                                                      |
| `include_agent_results` | boolean | `false` | Not available at this time. The server ignores it.                                                                                                                                      |
| `heartbeat_interval_ms` | integer | `30000` | Keep-alive heartbeat interval (milliseconds).                                                                                                                                           |
| `event_types`           | array   | all     | Not available at this time. The server sends all event types.                                                                                                                           |

## Examples

### Basic completion

```bash
curl -X POST https://app.promptshuttle.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "user", "content": [{"type": "text", "text": "What is the capital of France?"}]}
    ],
    "temperature": 0.3,
    "max_tokens": 100
  }'
```

### With customer tracking

```bash
curl -X POST https://app.promptshuttle.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Shuttle-Customer-Id: user_456" \
  -d '{
    "model": "anthropic/claude-sonnet-4-20250514",
    "messages": [
      {"role": "system", "content": [{"type": "text", "text": "You are a helpful assistant."}]},
      {"role": "user", "content": [{"type": "text", "text": "Explain quantum computing simply."}]}
    ]
  }'
```

### Using OpenAI Python SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://app.promptshuttle.com/api/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Write a haiku about APIs"}],
)

print(response.choices[0].message.content)
```

Do not set `stream=True` with the OpenAI SDK. The stream of this endpoint is the PromptShuttle event format, not OpenAI `chat.completion.chunk` objects, and the SDK cannot read it. To read the answer while the model writes it, read the event stream directly. See [Streaming (SSE)](https://docs.promptshuttle.com/api-reference/streaming.md#answer-text).

### With structured output

```bash
curl -X POST https://app.promptshuttle.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      {"role": "user", "content": [{"type": "text", "text": "List the planets in our solar system"}]}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "planets",
        "schema": {
          "type": "object",
          "properties": {
            "planets": {
              "type": "array",
              "items": { "type": "string" }
            }
          },
          "required": ["planets"]
        }
      }
    }
  }'
```

## Other endpoints

### List models

```
GET /api/v1/models/descriptors
```

Returns all supported models with capabilities, pricing, and token limits.

### List providers

```
GET /api/v1/providers
```

Returns all configured LLM providers and their supported models.

### Direct inference (PromptShuttle native)

```
POST /api/v1/inference
```

A simpler endpoint for direct LLM inference without OpenAI response formatting. Supports the same models and features.

Field names are camelCase on this endpoint.

| Field               | Type    | Description                                                                                                                                                                                                                                                                                                                                    |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`          | array   | ChatMessage array (PromptShuttle format)                                                                                                                                                                                                                                                                                                       |
| `model`             | string  | Model identifier                                                                                                                                                                                                                                                                                                                               |
| `environment`       | string  | Environment name for logging                                                                                                                                                                                                                                                                                                                   |
| `temperature`       | float   | Sampling temperature                                                                                                                                                                                                                                                                                                                           |
| `topP`              | float   | Nucleus sampling                                                                                                                                                                                                                                                                                                                               |
| `topK`              | integer | Top-k sampling (supported by some providers)                                                                                                                                                                                                                                                                                                   |
| `maxTokens`         | integer | Max output tokens                                                                                                                                                                                                                                                                                                                              |
| `seed`              | integer | Deterministic seed                                                                                                                                                                                                                                                                                                                             |
| `reasoningEffort`   | string  | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`. A level that the model does not accept is moved to the nearest accepted level. `none` turns thinking off if the model permits it.                                                                                                                                                |
| `maxThinkingTokens` | integer | Thinking budget. `0` turns thinking off if the model permits it. A model that always thinks uses its lowest level. On Claude models, you can send `0` together with `reasoningEffort` (`low`, `medium` or `high`): the model does not think, and it uses that effort for the answer. Claude Opus 5.5 and the Claude Fable models always think. |
| `responseSchema`    | object  | JSON Schema for structured outputs                                                                                                                                                                                                                                                                                                             |
| `vendorTools`       | array   | Provider-native tools (e.g. `web_search`)                                                                                                                                                                                                                                                                                                      |
| `injectedTools`     | array   | Tool definitions (`name`, `description`, `parameters`). The model can call them. PromptShuttle returns the calls to you and does not run them.                                                                                                                                                                                                 |
| `tags`              | array   | Tags for filtering in invocation log                                                                                                                                                                                                                                                                                                           |
| `isDebug`           | boolean | Enable verbose logging                                                                                                                                                                                                                                                                                                                         |
| `stream`            | boolean | Return Server-Sent Events. See [Streaming (SSE)](https://docs.promptshuttle.com/api-reference/streaming.md).                                                                                                                                                                                                                                   |
| `streamOptions`     | object  | See [Stream options](#stream-options). Used only when `stream` is `true`.                                                                                                                                                                                                                                                                      |

The response contains `id`, `creditsUsed`, `creditsLeft`, `milliseconds` and `result`.

`id` is the run ID. Use it to find the run in the invocation log or to stop the run. The response header `X-PromptShuttle-Request-Id` contains the same ID. The header is also present when the request fails. An error body contains the ID as `runId`.

A tool result that you send back in `messages` goes to the model as you wrote it. If the result is a string, the model reads that string. PromptShuttle does not encode it a second time.

### Tagging requests

The OpenAI request schema has no field for tags, so on `/api/v1/chat/completions` use the header instead:

```
X-Shuttle-Tags: TenderId:12313,Stage:analysis
```

Comma-separated, up to 20 tags. The header works on `/api/v1/inference` and `/api/v1/flows/{flowId}/runs` too, where it is merged with any `tags` in the body — handy for stamping a correlation tag centrally in an HTTP client rather than at every call site.

Tags are inherited by sub-agents, and drive both the invocation log filter and the [cost-per-tag report](https://docs.promptshuttle.com/platform/analytics.md#cost-per-tag).
