Back to Mana

Mana API

Read as MarkdownAgent documentation indexOpenAPI JSON

Do deep research or build programmatic workflows with Mana's API. The exploratory agent lets you create agent conversations, stream live events, answer follow-up questions, and retrieve generated artifacts from your own systems. The pipeline-builder agent lets you build data pipelines, store persistent artifacts/tables, and create dashboards.

The API reference is rendered at /docs/api from the OpenAPI document in api-reference/openapi.json.

Base URL

https://backend-alpha.mana.ai

Authentication

Use an API key from Settings -> API in the Mana app. Send it on authenticated public API requests with the X-API-Key header, or as Authorization: Bearer mana_xxx.

X-API-Key: mana_xxx

API keys inherit the user and organization permissions of the account that created them. Keep keys secret, rotate them after suspected exposure, and revoke unused keys from the Mana app.

GET /api/v1/health is unauthenticated and should be called without auth headers.

Common Workflow

  1. Create a conversation with POST /api/v1/conversations.
  2. Track it with either GET /api/v1/conversations/{conversation_id} polling or GET /api/v1/conversations/{conversation_id}/stream server-sent events.
  3. Retrieve generated files with GET /api/v1/conversations/{conversation_id}/artifacts.
  4. Download each artifact with GET /api/v1/artifacts/{artifact_id}/download.
  5. Send a follow-up with POST /api/v1/conversations and parentConversationId.

URLs that the API returns for API calls, such as streamUrl and downloadUrl, point at the API base URL. URLs such as conversationUrl and pipelineUrl open the Mana app.

Limits

Creating conversations and pipelines, and running whole pipelines, share a limit of 60 requests per minute per user. Above the limit, the API returns 429.

See the Quickstart for complete Python examples.