Authentication

Send the key

Use one of these headers, not both:

Authorization: Bearer sume_live_...

curl https://api.sume.com/v1/jobs?limit=1 \
  -H "Authorization: Bearer $SUME_API_KEY"

Your keys

Create and revoke keys in Dashboard → API keys. The full key is shown once, when you create it; the list shows only its prefix and last four characters.

• A key made in a team workspace belongs to that workspace, and its jobs spend that workspace's balance.
• A key reads only its own workspace's jobs. A job id from another workspace answers 404.
• Requests go to https://api.sume.com. A signed-in browser session sent there is refused; use a key.

Spend limit per key

Any key can have its own spend limit in US dollars: open the key's menu in API keys and choose Spend limit. Whoever made the key, or a team admin, sets it. It follows OpenRouter's per-key credit limit.

• It resets daily, weekly or monthly, or never. Windows are UTC: a day starts at 00:00, a week on Monday, a month on the 1st. Never counts everything the key has spent.
• It counts what that key spent in the current window. A refunded job gives its money back to the window.
• A call is priced before it runs, so a call that would take the key past its limit is refused before anything is charged: 403 api_key_spend_limit_exceeded, with no retry-after. Wait for resets_at or raise the limit.
• Other keys keep working, the workspace balance does not change, and a key with no limit works as before.

{
  "error": {
    "code": "api_key_spend_limit_exceeded",
    "message": "This API key is at its spend limit: $4.98 of $5.00 used, this request needs $0.04; resets 2026-11-01T00:00:00.000Z.",
    "request_id": "req_0ee311b4334e4b118a94c7d1c48577fd",
    "category": "quota",
    "stage": "usage_reservation",
    "retryable": false,
    "retry_after_seconds": null,
    "public_reason": "api_key_spend_limit_exceeded",
    "next_action": "fix_input",
    "details": {
      "limit_usd": "5.00",
      "spend_usd": "4.98",
      "requested_usd": "0.04",
      "limit_reset": "monthly",
      "resets_at": "2026-11-01T00:00:00.000Z"
    }
  }
}

Check a key

GET /v1/open/balance returns the balance the key spends, in US dollars, without spending anything. A 200 means the key works. GET /v1/me and GET /v1/balance are not routes of these keys: they answer 403 open_key_route_not_allowed.

curl https://api.sume.com/v1/open/balance \
  -H "Authorization: Bearer $SUME_API_KEY"

{
  "data": {
    "balance": 15.265433,
    "usage_this_month": 2.5,
    "auto_topup_setting": null,
    "billing_type": "credit-based",
    "currency": "USD",
    "balance_usd_micros": 15265433,
    "usage_this_month_usd_micros": 2500000
  }
}

Usage, transactions, receipts and top-ups are in the dashboard, under Settings → Usage and Settings → Billing, not in the API: GET /v1/open/usage answers 501 billing_in_dashboard.

Authentication errors

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key.",
    "request_id": "req_0ee311b4334e4b118a94c7d1c48577fd",
    "category": "auth",
    "stage": "auth",
    "retryable": false,
    "retry_after_seconds": null,
    "public_reason": "authentication_required",
    "next_action": "authenticate"
  }
}

Rotate a key

Create the new key, deploy it, then revoke the old one in the dashboard. A revoked key is refused at once.