# Quickstart Create an API key in the Mana app from **Settings -> API**, then store it in your shell: ```bash export MANA_API_KEY="mana_xxx" ``` The examples below use Python and `requests`. ## Health Check Call health without auth headers: ```python 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 ```python 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. ```python 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: ```python 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`: ```python 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. ```python 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`.