Skip to main content

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:

StatusWhenCodes
400the call or its body is wrong, or a limit is passed: per call, per day or per hour, as limit names itinvalid_params, unknown_filter_value, limit_exceeded, invalid_quote_token, bad_request
401no key, or a key that is unknown, revoked or expired, or of a suspended organizationunauthorised
402the available credits do not cover the call, or the free quota and the credits together do notinsufficient_balance, quota_exhausted
403the call is not allowed nowcoverage_exceeded, task_coverage_exceeded, org_suspended, agents_disabled, author_or_owner, estimate_limit
404no such tool or pathunknown_tool, not_found
405the path takes another method, named in Allowmethod_not_allowed
409the 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 heldquote_expired, quote_spent, quote_outdated, confirmation_required, corpus_updated, cohort_rebuilt, agent_changed, task_state, window_closed, rounds_used, unreserved_limit
413, 415the body is too large, or not sent as JSON in UTF-8bad_request
429too 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 hourrate_limited, task_rate
500the call failed on Megido's sideinternal_error
503not available now: a part of the corpus, a tool, an agent or Megido itself; try again later. After lock_timeout, call again after Retry-After; after service_unavailable, the call may have gone throughlayer_unavailable, tool_unavailable, agent_unavailable, lock_timeout, service_unavailable

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.

View as Markdown