Skip to main content
POST
/
responses
curl -X POST https://app.mavera.io/api/v1/responses \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mavera-1",
    "persona_id": "YOUR_PERSONA_ID",
    "input": "Explain quantum computing in simple terms."
  }'
{
  "id": "resp_abc123def456abc123def456",
  "object": "response",
  "created_at": 1706345678,
  "status": "completed",
  "model": "mavera-1",
  "output": [
    {
      "id": "msg_abc123def456",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Quantum computing uses qubits that can exist in multiple states simultaneously, enabling processing of many possibilities at once."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 68,
    "total_tokens": 110,
    "credits_used": 3
  }
}

Authorizations

​
Authorization
string
header
required

API key prefixed with mvra_live_. Create keys at Settings > Developer > API Keys.

Body

application/json
​
model
enum<string>
required

Model ID to use for the response.

Available options:
mavera-1
Example:

"mavera-1"

​
input
required

The input to the model. Can be a simple string for single-turn requests, or an array of input items for multi-turn conversations with tool calls.

Maximum string length: 100000
Example:

"Explain quantum computing in simple terms."

​
persona_id
string
required

Required. A Mavera persona CUID. The persona's curated system prompt is prepended to the conversation. Use GET /api/v1/personas to list available personas.

Example:

"clx1abc2d0001abcdef123456"

​
instructions
string

Optional system-level instructions to guide the model's behavior. Appended to the persona system prompt.

Example:

"Always respond in bullet points."

​
stream
boolean
default:false

If true, responses are streamed as named Server-Sent Events (SSE). The stream ends with data: [DONE].

Example:

false

​
text
object

Output format configuration. Replaces the legacy response_format field.

​
tools
object[]

A list of tools (functions) the model may call. Uses the flat Responses API format — name and parameters are directly on the tool object.

Maximum array length: 64
Example:
[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city name"
        }
      },
      "required": ["city"]
    }
  }
]
​
tool_choice

Controls which tool is called. auto (default) lets the model decide, none disables tools, required forces tool use, or { type: 'function', name: 'fn' } forces a specific function.

Available options:
auto,
none,
required
Example:

"auto"

​
analysis_mode
boolean
default:false

If true, returns structured analysis including emotional metrics, biases, confidence scores, and news relevance. Cannot be used with text.format.

Example:

false

​
canvas_mode
boolean
default:false

If true, enables artifact generation mode. The AI will generate structured content wrapped in <artifact> tags.

Example:

false

​
reasoning_effort
enum<string>
default:medium

Controls reasoning depth. high produces more thorough responses at the cost of latency.

Available options:
low,
medium,
high
Example:

"medium"

​
verbosity
enum<string>
default:medium

Controls response detail. low for concise, high for comprehensive.

Available options:
low,
medium,
high
Example:

"medium"

​
previous_response_id
string

The ID of a prior response to continue. Currently accepted but has no effect — pass full conversation history via input instead.

Example:

"resp_abc123def456"

​
store
boolean
default:false

Whether to store the response. Currently accepted but has no effect.

Response

Successful response. Returns a response object with the model-generated output and credit cost.

A completed response object.

​
id
string

Unique response ID with resp_ prefix.

Example:

"resp_abc123def456abc123def456"

​
object
enum<string>

Always response.

Available options:
response
Example:

"response"

​
created_at
integer

Unix timestamp (seconds) when the response was created.

Example:

1706345678

​
status
enum<string>

Response status.

Available options:
completed,
in_progress,
failed
Example:

"completed"

​
model
string

The model used.

Example:

"mavera-1"

​
output
object[]

Ordered list of output items. Typically a single message item with text, or one or more function_call items when the model wants to call tools.

A message output item.

​
usage
object

Token and credit usage.

​
server_tool_calls
object[]

Mavera's built-in server-side tools automatically executed during this request. Only present when server tools were used.

​
analysis
object

Structured analysis data. Present when analysis_mode is true.

​
parsed
object

Present when text.format.type is json_schema. Contains the parsed JSON object — a convenience field, same data is also in output[0].content[0].text.

Example:
{
  "sentiment": "positive",
  "score": 8.5,
  "summary": "Great product"
}