# 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; 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. |
| `bad_params` | 400 | Something is wrong with the params you sent. |
| `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. |

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)