Responses API - Mavera

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.

Migration Guide

Step-by-step instructions to migrate from Chat Completions to the Responses API

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.

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:

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

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.

​What Changed

​Why

​Migration Path

Migration Guide

​What’s New

​instructions Parameter

​Flat Tool Format

​Named SSE Events

​Backward Compatibility