Quickstart
1. Create an API key
Section titled “1. Create an API key”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_..."2. Ask a question
Section titled “2. Ask a question”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?"}'Python
Section titled “Python”/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)TypeScript
Section titled “TypeScript”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.
3. Ask a follow-up
Section titled “3. Ask a follow-up”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.
4. Don’t wait: run in the background
Section titled “4. Don’t wait: run in the background”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"What /v1/responses accepts
Section titled “What /v1/responses accepts”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 bemarvin.previous_response_idorconversation: 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.
- Long-running requests: timeouts, keep-alive whitespace and cancelling.
- API reference: every endpoint, including the research tools under
/v1/tools.