> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shumi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Base URL, authentication, the response envelope, error codes and quotas for the Shumi API.

The Shumi API returns market data and verdicts as JSON over HTTPS. The [CLI](/agents/cli) and the [MCP server](/agents/mcp) both call it. The API reference in the sidebar lists every endpoint with its parameters.

```
https://api.shumi.ai
```

Data routes live under `/api/cli`. `GET /api/cli/manifest` is public and lists the priced routes with their price and refresh interval.

## Authenticate a request

Every data route needs a bearer token in the `Authorization` header.

```bash theme={"dark"}
curl https://api.shumi.ai/api/cli/signal/BTC \
  -H "Authorization: Bearer shumi_sk_your_key_here"
```

| Token | Looks like | Where you get it |
| - | - | - |
| API key | starts with `shumi_sk_` | `shumi keys create` in the CLI. For servers, bots and agents |
| Login token | a JWT | `shumi login` stores it for the CLI |

Without a token the API answers `403 AUTH_REQUIRED`. With a malformed, unknown, expired or revoked one it answers `401 AUTH_INVALID`.

## Read the response

Every data route except the plain-word question route returns the same envelope: `schemaVersion`, `data` and `meta`. This is `GET /api/cli/signal/BTC` with `evidence` cut to one line.

```json theme={"dark"}
{
  "schemaVersion": 1,
  "data": {
    "symbol": "BTC",
    "verdict": "strong-bull",
    "score": 3.5,
    "confidence": "high",
    "evidence": ["trend (daily) is bullish since 2026-09-19T00:00:00.000Z"]
  },
  "meta": {
    "ts": "2026-09-23T13:46:57.027Z",
    "route": "signal/BTC",
    "as_of": "2026-09-23T13:46:56.725Z",
    "data_age_seconds": 0
  }
}
```

| Field | Meaning |
| - | - |
| `schemaVersion` | `1`. Changes only when the envelope's shape changes |
| `data` | The payload. Its shape depends on the route |
| `meta.ts` | When the API answered |
| `meta.route` | The route that answered |
| `meta.as_of` | When the newest data point in the payload was recorded. On most routes |
| `meta.data_age_seconds` | Seconds between `as_of` and `ts`. On most routes |

Check `data_age_seconds` before you act on a funding rate or a price. [Coverage](/platform/coverage#how-fresh-the-data-is) lists how often each kind of data refreshes.

## Handle an error

A failed call replaces `data` with `error`.

```json theme={"dark"}
{
  "schemaVersion": 1,
  "error": {
    "code": "BAD_REQUEST",
    "message": "action=coin requires ?symbol="
  }
}
```

| Code | HTTP | Meaning |
| - | - | - |
| `BAD_REQUEST` | 400 | A parameter is missing or invalid. The message names it |
| `AUTH_REQUIRED` | 403 | No token was sent |
| `AUTH_INVALID` | 401 | The token was rejected |
| `RATE_LIMITED` | 429 | Free quota used up on a route with no per-call price |
| `UPSTREAM_4XX` | same as upstream | A data source refused the request |
| `UPSTREAM_5XX` | 502 | A data source failed |
| `NETWORK` | 502 | A data source could not be reached |
| `INTERNAL` | 500 | Something else went wrong |

On upstream errors, `error.details` carries `upstreamStatus` and the upstream body.

<Note>
  `POST /api/cli`, the plain-word question route, streams its answer and returns a bare `{ "error": "..." }` on failure. Every other route uses the envelope above.
</Note>

## Know what a call costs

On the Free plan, every call to a data route counts as one question: 10 to start, then 1 per day, resetting at 00:00 UTC. After that, a priced route answers `402 Payment Required` with an x402 challenge: 0.005 USDC per data call, 0.05 USDC for a plain-word question, `pairs` or `walkforward`. [Pay Per Call](/agents/payments) shows the challenge and how to answer it. [Plans and Quotas](/platform/access) covers the plans.

To see which plan the API applies to your token:

```bash theme={"dark"}
curl https://api.shumi.ai/api/cli/billing/tier \
  -H "Authorization: Bearer $SHUMI_TOKEN"
```

```json theme={"dark"}
{ "data": { "tier": "pro", "source": "manual", "expiresAt": null } }
```

`GET /api/cli/billing/tier` and `GET /api/cli/manifest` never count against your quota and never ask for payment.

For a bot or dashboard on a timer, [Run a bot or dashboard](/agents/cli#run-a-bot-or-dashboard) shows which calls to repeat and which to save for a change.

## Stream live data

`GET /api/cli/watch/{stream}` keeps the connection open and sends one JSON object per line.

| Parameter | Values |
| - | - |
| `stream` | `funding`, `regime` or `sentiment` |
| `interval` | Seconds between polls, 10 to 300 |
| `diff=1` | Send a line only when the payload changed |

```bash theme={"dark"}
curl -N "https://api.shumi.ai/api/cli/watch/funding?interval=30" \
  -H "Authorization: Bearer $SHUMI_TOKEN"
```

A Free account can stream while it has questions left. Once the quota is spent, a stream answers `429 RATE_LIMITED` before the first line. Streams cannot be paid per call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.