The HTTP API
Your code can call the tools without an AI agent, over plain HTTP: the same tools, prices, coverage and limits as over MCP. The calls are charged to your organization's balance and appear in its Calls in the portal, marked API.
Calls
The API is at https://api.megido.io/v1. Each tool is POST /v1/tools/<tool>, with the tool's arguments as a JSON object in the body, sent as application/json; a tool without arguments takes {} or no body. The answer is what the tool returns over MCP: summary, data, and meta with what the call charged and the coverage it spent. GET /v1/tools lists the tools your key may call, with the JSON Schema of their arguments; the tools of tasks are listed only when your organization has agents.
curl -X POST https://api.megido.io/v1/tools/usage \
-H "Authorization: Bearer <your key>"
Keys
Send an API key of your organization in the Authorization header: Bearer sk_…. An account without registration has no keys: register it in the portal first. Keys are created in the Megido portal, under Keys and apps. A key acts for the person who holds it: tasks given with it are theirs, emails about those tasks go to them, and the hourly limits of tasks and messages count against them. When the person leaves your organization, their keys are revoked and calls with them get 401, so give a service the key of a member who stays. A chat app connected by signing in works over MCP only. The API takes no calls from web pages in a browser: keep the key on your server.
Estimates and retries
A paid tool takes estimate: true and answers with an estimate in place of the tool's data: data holds the most the call will charge, the coverage it will use and a quote_token. An estimate is free. Call the same tool with only quote_token to run exactly what was estimated, for no more than the estimate. Your organization may require an estimate for some tools and for calls above a price, limits.estimate_required_above in capabilities: such a call without one is refused with confirmation_required, which carries the estimate. A call that charges nothing is never refused this way.
Send an Idempotency-Key header with a paid call, create_task or update_task to make a retry safe. Use a value of your own, up to 200 characters, such as a UUID; values that start with task: are reserved. What the key does depends on the tool:
- With a paid call, the same key and the same arguments return the first answer without charging again; with other arguments or another tool the call is refused. A key is unique within your organization, whichever of its API keys sends it.
- With
create_task, the same key returns the task given with it, whatever the arguments, instead of a second task. - With
update_task, a reply or a revision request with the same key is written once, even if its text differs, and the retry does not count against the hourly limit of messages. The other actions do not read the key.
The keys of create_task and update_task are matched among the tasks and messages of the person whose API key sends them. It is the key that _meta.idempotency_key carries over MCP, so a call made over one can be retried over the other.
A paid call's answer repeated by its key, or by a quote_token that has already run, has meta.replayed: true: its meta.charge is what the first call charged, and nothing is charged again.
Give a call up to a minute to answer. A call that times out, breaks off or gets 503 with service_unavailable may have gone through: call it again with the same key, which returns its answer if it did.
Errors
Every error has the body {"error": {"code": "…", "message": "…"}} with the details of its code, such as the estimate that confirmation_required carries. A refusal charges nothing, and its message says what to do; When a call is refused and Tasks for Megido's agents in the client guide explain the main ones. The status follows from the code:
| Status | When | Codes |
|---|---|---|
| 400 | the call or its body is wrong, or a limit is passed: per call, per day or per hour, as limit names it | invalid_, unknown_, limit_, invalid_, bad_ |
| 401 | no key, or a key that is unknown, revoked or expired, or of a suspended organization | unauthorised |
| 402 | the available credits do not cover the call, or the free quota and the credits together do not | insufficient_, quota_ |
| 403 | the call is not allowed now | coverage_, task_, org_, agents_, author_, estimate_ |
| 404 | no such tool or path | unknown_, not_ |
| 405 | the path takes another method, named in Allow | method_ |
| 409 | the call conflicts with the state of things: an estimate expired, ran, is required or counted on free quota that is spent, the corpus or a niche was rebuilt, the agent or the task changed, or too many tasks wait with their price not held | quote_, quote_, quote_, confirmation_, corpus_, cohort_, agent_, task_, window_, rounds_, unreserved_ |
| 413, 415 | the body is too large, or not sent as JSON in UTF-8 | bad_ |
| 429 | too many calls in a second, or from an address that sent keys Megido does not know, both with Retry-After; or too many tasks in an hour | rate_, task_ |
| 500 | the call failed on Megido's side | internal_ |
| 503 | not available now: a part of the corpus, a tool, an agent or Megido itself; try again later. After lock_, call again after Retry-After; after service_, the call may have gone through | layer_, tool_, agent_, lock_, service_ |
Every answer carries X-Request-Id: quote it when you write to Megido support.
Limits
The calls of one key share one limit per second, over MCP and the HTTP API together: per_key_rps in usage and capabilities gives it, and past it the answer is 429 with Retry-After. Calls with keys Megido does not know close their address for some minutes, to every key: a valid key from that address then gets 429 with Retry-After as well, so stop code that keeps sending a wrong key. A 503 with lock_timeout means the call waited too long behind other calls of your organization: call again after Retry-After. Credits, coverage, reveals and tasks are your organization's, shared with its agents, its chat and its people in the portal; usage shows the credits and the coverage left.
Tasks
The tools of tasks work as Tasks for Megido's agents describes. A task priced above your organization's consent_ceiling, 0 by default, waits for a person of your organization to confirm it in the Megido portal; Megido support raises the ceiling on request. Nothing notifies you of a change, and the API sends no webhooks: read a task with get_task every few minutes. After you reply to the agent's question, the task shows awaiting_client until the agent has read the reply, usually within seconds: do not reply again. Files can be attached to a brief only in the portal.
The reference
The OpenAPI 3.1 document of the API, with every tool's arguments, answers and errors, is at GET /v1/openapi.json, free and without a key. Megido ships no SDK: generate a client from the document. Its version is the date of its latest change, such as 2026.11.9. The Megido website shows it as the API reference, with the API's changelog: every change to its paths, fields, types and error codes, dated.