Skip to content

Quickstart

In the Marvin app, open your account settings and go to API keys. Create a key and copy it. It starts with ak_.

Keep it in an environment variable rather than in your code:

export MARVIN_API_KEY="ak_..."

The base URL is https://app-api.marvin-labs.com. Send the key as a bearer token.

curl -s https://app-api.marvin-labs.com/v1/responses \
-H "Authorization: Bearer $MARVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "What does Apple make, and how much of its revenue comes from services?"}'

/v1/responses follows OpenAI’s Responses API, so the official OpenAI SDK works with only the base URL and key changed (pip install openai):

import os
from openai import OpenAI
client = OpenAI(
base_url="https://app-api.marvin-labs.com/v1",
api_key=os.environ["MARVIN_API_KEY"],
timeout=3600, # a turn can take minutes; see Long-running requests
)
response = client.responses.create(
model="marvin",
input="What does Apple make, and how much of its revenue comes from services?",
)
print(response.output_text)

With the official OpenAI SDK (npm install openai):

import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://app-api.marvin-labs.com/v1',
apiKey: process.env.MARVIN_API_KEY,
timeout: 3_600_000, // a turn can take minutes; see Long-running requests
});
const response = await client.responses.create({
model: 'marvin',
input: 'What does Apple make, and how much of its revenue comes from services?',
});
console.log(response.output_text);

The answer is in output_text. The response also carries its id and conversation.id.

Pass the previous response’s id, and Marvin continues the same conversation:

follow_up = client.responses.create(
model="marvin",
input="And how has that share changed over the last five years?",
previous_response_id=response.id,
)

Every API conversation also appears in the Marvin app’s chat sidebar, and conversation continues any conversation you own, including one you started in the app:

client.responses.create(model="marvin", input="Summarise this.", conversation="<conversation id>")

The conversation id is the id in the app’s /chat/<id> URL.

A turn can take several minutes. To get control back at once, send background: true and poll:

import time
response = client.responses.create(model="marvin", input="...", background=True)
while response.status in ("queued", "in_progress"):
time.sleep(5)
response = client.responses.retrieve(response.id)
print(response.status, response.output_text)

The same in curl:

curl -s https://app-api.marvin-labs.com/v1/responses/$RESPONSE_ID \
-H "Authorization: Bearer $MARVIN_API_KEY"

Marvin is one model, so most of the Responses API’s options do not apply:

  • input: a string, or a list holding one user message.
  • model: optional. If given, it must be marvin.
  • previous_response_id or conversation: optional, one or the other.
  • background: optional.

Any other parameter (tools, temperature, stream and so on) is refused with a 422. usage is always null, because the API is billed in credits, not tokens.

Marvin never stops to ask you a question during an API turn. Where it would ask in the app, it states the assumption it made and answers.