Back to Mana

Quickstart

Read as MarkdownAgent documentation indexOpenAPI JSON

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 exploratory for a research answer from the Exploratory agent.
  • Send pipeline-builder to 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.