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

# Responses API

> Mavera has migrated from Chat Completions to the OpenAI Responses API format

**April 2026**

Mavera has migrated from the OpenAI **Chat Completions** format to the OpenAI **Responses API** format. This is the same API shape used by OpenAI's latest SDKs and brings a cleaner interface, flat tool definitions, and named streaming events.

## What Changed

| Area                  | Chat Completions (before)             | Responses API (after)                           |
| --------------------- | ------------------------------------- | ----------------------------------------------- |
| **Endpoint**          | `POST /api/v1/chat/completions`       | `POST /api/v1/responses`                        |
| **SDK method**        | `client.chat.completions.create()`    | `client.responses.create()`                     |
| **Input format**      | `messages: [{role, content}]`         | `input: "string"` or `input: [{role, content}]` |
| **System messages**   | Part of `messages` array              | `instructions` parameter                        |
| **Response output**   | `response.choices[0].message.content` | `response.output[0].content[0].text`            |
| **Streaming**         | `stream=True` flag                    | `client.responses.stream()` with named events   |
| **Tool format**       | Nested `{function: {name, ...}}`      | Flat `{name, description, parameters}`          |
| **Tool results**      | `{role: "tool", tool_call_id}`        | `{type: "function_call_output", call_id}`       |
| **Structured output** | `response_format`                     | `text: {format: {...}}` via `extra_body`        |
| **Token fields**      | `prompt_tokens` / `completion_tokens` | `input_tokens` / `output_tokens`                |
| **Finish signal**     | `finish_reason: "stop"`               | `status: "completed"`                           |

## Why

The Responses API is OpenAI's latest standard and provides several improvements:

* **Simpler input** — pass a plain string for single-turn queries instead of wrapping everything in a messages array
* **Dedicated `instructions` parameter** — cleanly separates system-level guidance from user input, and appends to the persona's built-in prompt
* **Flat tool format** — no more nested `function` wrapper; tool properties are top-level
* **Named SSE events** — `response.created`, `response.output_text.delta`, `response.completed` make stream parsing more explicit
* **Cleaner response shape** — no `choices` array; output items are typed (`message`, `function_call`)

## Migration Path

We've published a detailed migration guide that covers every change with before/after code examples in Python, JavaScript, and cURL.

<Card title="Migration Guide" icon="arrow-right" href="/cookbooks/migrate-chat-to-responses">
  Step-by-step instructions to migrate from Chat Completions to the Responses API
</Card>

## What's New

### `instructions` Parameter

System messages are replaced by the `instructions` parameter. Instructions are appended to the persona's built-in system prompt, so you get persona context plus your task-specific guidance without message array management.

```python theme={"dark"}
response = client.responses.create(
    model="mavera-1",
    input="Analyze brand loyalty trends.",
    instructions="You are a market research analyst. Focus on Gen Z.",
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
)
```

### Flat Tool Format

Tool definitions no longer require a `function` wrapper. Properties are top-level:

```python theme={"dark"}
tools = [
    {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    }
]
```

### Named SSE Events

Streaming now uses named event types instead of generic data chunks:

| Event                        | Description                             |
| ---------------------------- | --------------------------------------- |
| `response.created`           | Response object created                 |
| `response.output_text.delta` | A text chunk — access via `event.delta` |
| `response.completed`         | Response is fully complete              |

```python theme={"dark"}
with client.responses.stream(
    model="mavera-1",
    input="Write a product description",
    extra_body={"persona_id": "YOUR_PERSONA_ID"},
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
```

## Backward Compatibility

The Chat Completions endpoint (`/api/v1/chat/completions`) remains available during the transition period. All new features and documentation target the Responses API exclusively.