API

Get started

1. 1

   Mint

   Session cookie. Plaintext mago_sk_ once. Customer keys cannot call /api/keys.

   RequestCopy

   curl -sS https://mago.team/api/keys/generate \
     -H "Cookie: mago-token=…" \
     -H "Content-Type: application/json" \
     -d '{"name":"desk"}'

2. 2

   Quote

   Milliscale estimate. No debit. estimated_credits is what the scan reserves.

   RequestResponse

   Copy

   curl -sS https://mago.team/api/v1/quote \
     -H "X-API-Key: mago_sk_…" \
     -H "Content-Type: application/json" \
     -d '{"target":"example.com"}'

3. 3

   Scan

   authorization_confirmed must be true. Live keys hunt. mago_sk_test_ is client-dev: sandbox-example, no hunt.

   RequestResponseSandbox

   Copy

   curl -sS https://mago.team/api/v1/scans \
     -H "X-API-Key: mago_sk_…" \
     -H "Content-Type: application/json" \
     -d '{"target":"example.com","authorization_confirmed": true,"passive_only":true,"ai":false}'

4. 4

   Stream

   SSE until done, failed, or cancelled. Then GET the report.

   StreamReportFixture

   Copy

   curl -N https://mago.team/api/billing/order/{order_id}/stream \
     -H "X-API-Key: mago_sk_…"

Authentication

Hunt calls take X-API-Key or Authorization: Bearer mago_sk_. Mint stays on the session cookie. HTTPS only.

Reference

Public hunt surface. Examples are milliscale for example.com with AI off. Quote is the live figure.

curl -sS https://mago.team/api/v1/quote \
  -H "X-API-Key: mago_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com"}'

{
  "product": "search",
  "estimated_credits": 208,
  "charged_credits": 208,
  "module_credits": 208,
  "token_credits": 0,
  "offer_id": "domain",
  "spells": ["dns_deep", "subdomain_enum", "whois_osint"]
}

curl -sS https://mago.team/api/v1/scans \
  -H "X-API-Key: mago_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com","authorization_confirmed": true,"passive_only":true,"ai":false}'

{
  "order_id": "ord_01EXAMPLE",
  "credits_reserved": 208,
  "status": "queued"
}

curl -sS https://mago.team/api/v1/scans/{order_id} \
  -H "X-API-Key: mago_sk_…"

{
  "order_id": "ord_01EXAMPLE",
  "status": "running",
  "target": "example.com",
  "product": "search",
  "progress": { "done": 4, "total": 18 }
}

curl -N https://mago.team/api/billing/order/{order_id}/stream \
  -H "X-API-Key: mago_sk_…"

{
  "done": 4,
  "total": 18,
  "status": "running",
  "order_id": "ord_01EXAMPLE"
}

curl -sS https://mago.team/api/v1/reports/{order_id} \
  -H "X-API-Key: mago_sk_…"

{
  "target": { "value": "example.com", "type": "domain" },
  "findings": [],
  "metadata": { "order_id": "ord_01EXAMPLE", "generated_by": "MAGO" }
}

curl -sS https://mago.team/api/v1/credits \
  -H "X-API-Key: mago_sk_…"

{
  "monthly": 3000,
  "permanent": 0,
  "total": 3000
}

curl -sS https://mago.team/api/keys/generate \
  -H "Cookie: mago-token=…" \
  -H "Content-Type: application/json" \
  -d '{"name":"desk"}'

{
  "api_key": "mago_sk_…",
  "key_id": "key_…",
  "name": "desk",
  "created_at": "2026-10-03T00:00:00+00:00"
}

Errors

JSON bodies. A hunt that exceeds the wallet is 402. Another account's order_id is 404.

{
  "detail": {
    "error": "AuthorizationRequired",
    "message": "You must confirm authorization to scan this target."
  }
}

{
  "detail": {
    "error": "AuthorizationRequired",
    "message": "You must confirm authorization to scan this target."
  }
}

{ "detail": "Invalid API key" }

{ "detail": "Insufficient credits: need 208, have 50" }

{
  "detail": {
    "error": "ApiAccessRequired",
    "required_plan": "pro",
    "current_plan": "solo",
    "upgrade_url": "/pricing"
  }
}