# Use Intelligence from your own code or agent

MixShift Intelligence is reachable over REST and MCP with the same credential you use for the rest of the Builder Platform, under its own scope.

## REST

- `GET /api/intelligence/ids` returns the deployed catalog: each request's id, version, content revision, service, and a one-line purpose.
- `POST /api/intelligence/run` with `{ "id", "params" }` runs a request. Add `"evidence": true` for the What We Know statements, and `"async": true` on a large account (see [Limits and freshness](/knowledge-base/intelligence/reference/limits-and-freshness)).
- `GET /api/intelligence/runs/<runId>` polls or fetches an async run you started.

## MCP tools

The same capability is exposed as `intelligence_catalog`, `intelligence_run`, `intelligence_poll`, and `intelligence_get`, so an AI client can call a request conversationally. See [Connect AI tools over MCP](/knowledge-base/builder-platform/how-to/connect-ai-tools-over-mcp) for how to point a client at the MCP server in the first place.

## The scope

Every call, REST or MCP, needs `intelligence:read`. Interactive sign-ins get it by default, including a Claude connector and MixShift added to ChatGPT as a custom app. A Claude connector added before September 27 needs removing and adding again first; if you added MixShift to ChatGPT before September 27, add it again. A service credential needs it granted explicitly. See [Get access](/knowledge-base/intelligence/getting-started/get-access).

## Not part of /v1

Intelligence is not part of the documented `/v1` partner contract. Its result shape is versioned by the engine itself, not by the `/v1` conventions, so build against the envelope fields described here rather than assuming `/v1` semantics.

## Error kinds

Every failure comes back as `{ ok: false, kind, friendly }`.

| Kind | Status | Meaning |
| --- | --- | --- |
| `not_enrolled` | 403 | MixShift has switched Intelligence off for this account. |
| `insufficient_scope` | 403 | Your credential is missing `intelligence:read`. Also a 403, and easy to mistake for `not_enrolled`: that one means the account does not have Intelligence, this one means your credential does not. For a service credential, ask a MixShift admin to reissue it with the scope. For a Claude connector you added before September 27, remove it and add it again. If you added MixShift to ChatGPT before September 27, add it again: reconnecting keeps the access it was first set up with. |
| `bad_params` | 400 | Something is wrong with the params you sent. This also covers a filter the service cannot resolve yet, which is rejected outright rather than accepted and quietly ignored. |
| `merchant_not_resolved` | 422 | The merchant selector did not resolve to an account. |
| `account_too_large_use_async` | 422 | Retry the same request with `"async": true`. |
| `no_data_for_period` | 404 | Nothing to compute for the period you asked about. |
| `busy` | 429 | The account (or the service) is at its concurrency cap. Retry shortly. |
| `throttled` | 429 | The gateway's own rate limit, rather than the Intelligence concurrency cap. Honour `Retry-After`. |

Full parameter and endpoint reference: [mcp.mixshift.io/developers#intelligence](https://mcp.mixshift.io/developers#intelligence).

## Related

- [Get access](/knowledge-base/intelligence/getting-started/get-access)
- [Run an insight from the command line](/knowledge-base/intelligence/how-to/run-an-insight-from-the-command-line)
- [Limits and freshness](/knowledge-base/intelligence/reference/limits-and-freshness)