Create an API key in the Mana app from Settings -> API, then store it in your shell:
export MANA_API_KEY="mana_xxx"
The examples below use Python and requests.
Health Check
Call health without auth headers:
import requests
BASE_URL = "https://backend-alpha.mana.ai"
response = requests.get(f"{BASE_URL}/api/v1/health", timeout=30)
response.raise_for_status()
print(response.json())
Choose an Agent
POST /api/v1/conversations takes an optional agentType:
- Leave it out, or send
jethro, to let Mana route the request as the Mana app does. Mana answers it directly or hands it to a specialist agent, such as Pipeline Builder when you ask for a Pipeline. The specialist runs in a conversation of its own. - Send
exploratoryfor a research answer from the Exploratory agent. - Send
pipeline-builderto build or change a Pipeline with Pipeline Builder directly.
Jethro picks the agent and model for each turn. If you send model, reasoning or responseSchema without naming exploratory or pipeline-builder, the request fails with 422. The examples below name exploratory.
Poll Status and Download Artifacts
import os
import time
from pathlib import Path
import requests
BASE_URL = "https://backend-alpha.mana.ai"
API_KEY = os.environ.get("MANA_API_KEY", "mana_xxx")
HEADERS = {"X-API-Key": API_KEY}
# 1) Launch an exploratory agent run.
create_response = requests.post(
f"{BASE_URL}/api/v1/conversations",
headers=HEADERS,
json={
"prompt": "what is the stock price of tsla",
"agentType": "exploratory",
},
timeout=30,
)
create_response.raise_for_status()
conversation_id = create_response.json()["conversationId"]
print("conversation:", conversation_id)
# 2) Poll status until terminal. Polling reports a stopped run as "canceled".
terminal_statuses = {"completed", "failed", "canceled"}
while True:
status_response = requests.get(
f"{BASE_URL}/api/v1/conversations/{conversation_id}",
headers=HEADERS,
timeout=30,
)
status_response.raise_for_status()
status = status_response.json()["status"]
print("status:", status)
if status in terminal_statuses:
break
time.sleep(2)
if status != "completed":
raise RuntimeError(f"conversation ended with status={status}")
# 3) Fetch artifact metadata.
artifacts_response = requests.get(
f"{BASE_URL}/api/v1/conversations/{conversation_id}/artifacts",
headers=HEADERS,
timeout=30,
)
artifacts_response.raise_for_status()
artifacts = artifacts_response.json()
# 4) Download every artifact.
output_dir = Path("downloads")
output_dir.mkdir(exist_ok=True)
for artifact in artifacts:
artifact_id = artifact["id"]
download_response = requests.get(
f"{BASE_URL}/api/v1/artifacts/{artifact_id}/download",
headers=HEADERS,
allow_redirects=True,
timeout=120,
)
download_response.raise_for_status()
filename = artifact.get("filePath") or f"{artifact_id}.bin"
target_path = output_dir / filename.split("/")[-1]
target_path.write_bytes(download_response.content)
print("downloaded:", target_path)
Artifact downloads return 200 with the original file bytes, the stored content type, and an attachment filename. A single Range: bytes=0-3 request returns 206 with Content-Range and those four bytes. Unsatisfiable ranges return 416; multi-range requests return the full file with 200.
Stream Events with SSE
Use the stream endpoint when you want live conversation updates instead of polling.
import json
import os
import requests
BASE_URL = "https://backend-alpha.mana.ai"
API_KEY = os.environ.get("MANA_API_KEY", "mana_xxx")
HEADERS = {
"X-API-Key": API_KEY,
"Accept": "text/event-stream",
}
# 1) Start run.
create_response = requests.post(
f"{BASE_URL}/api/v1/conversations",
headers={"X-API-Key": API_KEY},
json={
"prompt": "what is the stock price of tsla",
"agentType": "exploratory",
},
timeout=30,
)
create_response.raise_for_status()
conversation_id = create_response.json()["conversationId"]
# 2) Stream events with SSE.
with requests.get(
f"{BASE_URL}/api/v1/conversations/{conversation_id}/stream",
headers=HEADERS,
stream=True,
timeout=600,
) as response:
response.raise_for_status()
event_name = None
live = False
terminal_statuses = {"completed", "failed", "cancelled"}
for line in response.iter_lines(decode_unicode=True):
if not line:
event_name = None
continue
if line.startswith("event: "):
event_name = line[len("event: ") :]
continue
if line.startswith("data: "):
payload = json.loads(line[len("data: ") :])
print(event_name, payload)
if event_name == "stream_phase" and payload.get("phase") == "live":
live = True
elif (
live
and event_name == "conversation_status"
and payload.get("status") in terminal_statuses
):
# A late copy of an earlier turn's status can arrive after
# stream_phase, so confirm with the status endpoint first.
current = requests.get(
f"{BASE_URL}/api/v1/conversations/{conversation_id}",
headers={"X-API-Key": API_KEY},
timeout=30,
).json()["status"]
if current in {"completed", "failed", "canceled"}:
break
The stream sends a connection event, replays the conversation's history, sends stream_phase with phase: "live", and then sends live events. Each event name is a message type, such as thinking, step, report, artifact_generated or conversation_status. Stream payloads use snake_case keys, and the stream spells a stopped run cancelled.
Replayed history can hold terminal statuses of earlier turns, and a late copy of one can arrive after stream_phase. Treat a terminal conversation_status as a signal to check GET /api/v1/conversations/{conversation_id}, as the loop above does, rather than as the end by itself. If the turn ended before you connected, its terminal status is in the replay and the stream closes on its own after a few idle seconds; the status endpoint then gives the result.
Read the Answer
The final answer is a report message. Read it from the conversation's messages:
messages = requests.get(
f"{BASE_URL}/api/v1/conversations/{conversation_id}/messages",
headers=HEADERS,
timeout=30,
).json()
reports = [m["content"] for m in messages if m["messageType"] == "report"]
print(reports[-1])
To get structured data instead of prose, pass a JSON Schema as responseSchema when you create an exploratory conversation, then read GET /api/v1/conversations/{conversation_id}/structured-output. A follow-up in a Pipeline Builder conversation cannot use responseSchema: those conversations run durably, and durable runs do not support it.
Answer a Question
Exploratory and Pipeline Builder runs started through the API do not stop to ask questions: they make reasonable assumptions and continue. Only Plan Mode runs ask, and the public API cannot start Plan Mode yet.
When a run does wait for an answer, the status response has a pendingQuestion with a form_id and a list of questions; each has question text and optional options. Answer with POST /api/v1/conversations/{conversation_id}/respond:
status_payload = requests.get(
f"{BASE_URL}/api/v1/conversations/{conversation_id}",
headers=HEADERS,
timeout=30,
).json()
pending = status_payload["pendingQuestion"]
answer_response = requests.post(
f"{BASE_URL}/api/v1/conversations/{conversation_id}/respond",
headers=HEADERS,
json={
"formId": pending["form_id"],
"answers": [
{"questionIndex": 0, "selectedOptions": ["Yes"]},
{"questionIndex": 1, "textAnswer": "Use the last 5 years."},
],
},
timeout=30,
)
answer_response.raise_for_status()
Send a Follow-Up
To add a message to an existing conversation, pass parentConversationId. The API returns the same conversationId, and the agent keeps the earlier context. Leave out agentType to keep the conversation's current agent.
follow_up_response = requests.post(
f"{BASE_URL}/api/v1/conversations",
headers=HEADERS,
json={
"prompt": "summarize the result in one sentence",
"parentConversationId": conversation_id,
},
timeout=30,
)
follow_up_response.raise_for_status()
assert follow_up_response.json()["conversationId"] == conversation_id
A conversation runs one turn at a time. A follow-up sent while a turn is still running returns 409; wait for a terminal status, or stop the turn with POST /api/v1/conversations/{conversation_id}/cancel. Right after a follow-up, the status reads pending until the new turn starts.
Limits
POST /api/v1/conversations, POST /api/v1/pipelines and POST /api/v1/pipelines/{pipeline_id}/runs share a limit of 60 requests per minute per user. Above it they return 429.