Create a response

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
  }
}

{
  "error": {
    "message": "Model 'unknown-model' is not supported. Use GET /api/v1/models to see available models.",
    "type": "invalid_request_error",
    "code": "invalid_model",
    "param": "model"
  }
}

{
  "error": {
    "message": "Invalid API key. Ensure your key starts with 'mvra_live_' and has not been revoked.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

{
  "error": {
    "message": "Insufficient credits. Please upgrade your subscription or wait for your next billing cycle.",
    "type": "insufficient_credits",
    "code": "credits_exhausted",
    "param": null
  }
}

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

{
  "error": {
    "message": "An internal error occurred. Please try again later.",
    "type": "api_error",
    "code": "internal_error",
    "param": null
  }
}

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.

Show child attributes

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

Show child attributes

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.

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.

Option 1
Option 2

Show child attributes

usage

object

Token and credit usage.

Show child attributes

server_tool_calls

object[]

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

Show child attributes

analysis

object

Structured analysis data. Present when analysis_mode is true.

Show child attributes

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"
}

Health check

List available models

⌘I

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
  }
}

{
  "error": {
    "message": "Model 'unknown-model' is not supported. Use GET /api/v1/models to see available models.",
    "type": "invalid_request_error",
    "code": "invalid_model",
    "param": "model"
  }
}

{
  "error": {
    "message": "Invalid API key. Ensure your key starts with 'mvra_live_' and has not been revoked.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

{
  "error": {
    "message": "Insufficient credits. Please upgrade your subscription or wait for your next billing cycle.",
    "type": "insufficient_credits",
    "code": "credits_exhausted",
    "param": null
  }
}

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  }
}

{
  "error": {
    "message": "An internal error occurred. Please try again later.",
    "type": "api_error",
    "code": "internal_error",
    "param": null
  }
}

System

Responses

Models

Personas

Custom Personas

Brand Voice

Generations

Mave

Workspaces

Projects

Meetings

Files

Folders

Video Analysis

Focus Groups

News

Usage

Create a response

Authorizations

Body

Response