Skip to main content
POST
/
chat
/
completions
curl -X POST https://app.mavera.io/api/v1/chat/completions \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mavera-1",
    "persona_id": "YOUR_PERSONA_ID",
    "messages": [
      { "role": "user", "content": "Explain quantum computing in simple terms." }
    ]
  }'
{
  "id": "chatcmpl_abc123def456",
  "object": "chat.completion",
  "created": 1706345678,
  "model": "mavera-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing uses quantum bits (qubits) that can exist in multiple states simultaneously, unlike classical bits that are either 0 or 1. This allows quantum computers to process many possibilities at once, making them powerful for specific tasks like cryptography and molecular simulation."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "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 completion.

Available options:
mavera-1
Example:

"mavera-1"

​
messages
object[]
required

A list of messages comprising the conversation so far. Must contain between 1 and 128 messages.

Required array length: 1 - 128 elements
Example:
[
  {
    "role": "user",
    "content": "What's in this image?",
    "attachments": [
      {
        "type": "image",
        "url": "https://your-bucket.s3.amazonaws.com/image.png"
      }
    ]
  }
]
​
persona_id
string
required

Required. A Mavera persona CUID. The persona's curated system prompt is prepended to the conversation, giving the model a specific personality and expertise. Use GET /api/v1/personas to list available personas.

Example:

"clx1abc2d0001abcdef123456"

​
stream
boolean
default:false

If true, partial message deltas will be sent as Server-Sent Events (SSE). The stream is terminated by a data: [DONE] message.

Example:

false

​
analysis_mode
boolean
default:false

If true, returns structured analysis data including emotional metrics, biases, confidence scores, news relevance, and more.

Example:

false

​
canvas_mode
boolean
default:false

If true, enables artifact generation mode. The AI will generate structured content (code, documents) wrapped in <artifact> tags, suitable for collaborative editing and content creation.

Example:

false

​
reasoning_effort
enum<string>
default:medium

Controls how much computational effort the AI uses for reasoning. Higher effort leads to more thorough responses but may take longer.

Available options:
low,
medium,
high
Example:

"medium"

​
verbosity
enum<string>
default:medium

Controls how detailed the AI's responses will be. 'low' for concise, 'high' for comprehensive explanations.

Available options:
low,
medium,
high
Example:

"medium"

Response

Successful chat completion. Returns the model-generated message along with credit cost.

​
id
string

A unique identifier for this completion.

Example:

"chatcmpl_abc123def456"

​
object
enum<string>

The object type, always chat.completion.

Available options:
chat.completion
Example:

"chat.completion"

​
created
integer

Unix timestamp (in seconds) of when the completion was created.

Example:

1706345678

​
model
string

The model used for this completion.

Example:

"mavera-1"

​
choices
object[]

A list of completion choices. Currently always contains a single choice.

​
usage
object

Credit cost for this request.

​
tool_calls
object[]

List of tools that were automatically invoked during this request. Only present if tools were used.

​
analysis
object

Structured analysis data returned when analysis_mode or mosaic_mode is enabled. Contains emotional metrics, biases, confidence scores, news relevance, and more.