API and MCP

REST API

Everything Topographer shows in the dashboard, you can also read and change through the REST API: surveys and reports, portfolios, data health, credentials, organizations, teams and the activity log. Scripts and CI use an API token; the Surveyor CLI uses a Spice Pass.

Make your first call

Create an API token

In the dashboard, open the menu (☰), choose Credentials, and choose New API Token. Pick a lifetime and copy the token: it is shown once. See Spice Passes and credentials.
Find your project id

The project id is the long id in the dashboard address after /app/, for example https://dashboard.spicelabs.io/app/<project-id>/....
Call the API
```
export SPICE_API_TOKEN="<your API token>"
curl -s -H "Authorization: Bearer $SPICE_API_TOKEN" \
  "https://api.spicelabs.io/api/v1/project/<project-id>/v1/job?topLevel=true&limit=5"
```
```
$env:SPICE_API_TOKEN = "<your API token>"
Invoke-RestMethod -Headers @{ Authorization = "Bearer $env:SPICE_API_TOKEN" } `
  -Uri "https://api.spicelabs.io/api/v1/project/<project-id>/v1/job?topLevel=true&limit=5"
```
This lists the five most recent surveys and other jobs in the project.

The API reference

The API reference on this site lists every operation with its parameters, request body, answers and error codes. In the dashboard, open API in your project for the same reference with a Run it console that sends the call as you, from the browser.

The reference is also available as an OpenAPI 3.1 document:

Document	Address	Token
General reference	`https://api.spicelabs.io/api/v1/openapi.json`	Not needed
Your project’s reference	`https://api.spicelabs.io/api/v1/project/<project-id>/openapi.json`	API token or sign-in

Load either into an OpenAPI tool or code generator. AI assistants can read the reference directly through the MCP.

Addresses

Family	Path	Example
A project	`/api/v1/project/<project-id>/...`	`/api/v1/project/<project-id>/v1/portfolio`
An organization	`/api/v1/org/<org-id>/...`	`/api/v1/org/<org-id>/team`
You	`/api/v1/user/...`	`/api/v1/user/project`

A second version segment after the project id, as in /v1/portfolio, is the version of that family of resources. A breaking change to a family arrives as a v2 path next to the v1 one.

Credentials

Every request carries Authorization: Bearer <credential>.

Credential	Use it for	Where it comes from
API token	Scripts, CI and integrations	Credentials > New API Token. You choose its lifetime, from 1 day to 1 year. Its permissions are at most your own.
Spice Pass	Uploading surveys from the Surveyor CLI, and nothing else	Credentials > New Spice Pass
Dashboard sign-in	The dashboard and the Run it console	Signing in
MCP access	AI assistants	Approving an assistant on the consent page. See Connect an AI assistant.

Each operation in the reference says which credentials it accepts. Creating and revoking credentials needs a dashboard sign-in.

Limits

Rate. Each credential may make 600 requests a minute. Past that, the API answers 429 with the code rate_limited; wait a moment and send the request again.
Pages. Every list takes limit, from 1 to 10000 (1000 when you leave it out). Lists that grow over time, such as activity, jobs and data health runs, page with after or before set to an id from the previous page; the answer’s pagination object holds firstId, lastId, hasMore and total. Computed results, such as a portfolio rank or a report section, page with offset.

Errors

Every error is a JSON body with a message, the HTTP status and a machine-readable code:

{ "error": "Project not found", "status": 404, "code": "not_found" }

Write your code against code, not the message. An invalid_parameter error also names the parameter, and a permission_denied error names the permission you are missing. The reference lists every code.

Changes and deprecation

New operations, optional parameters, answer fields and error codes can appear at any time, so ignore fields you do not know. Nothing is removed or changed in a breaking way without being deprecated first: the reference marks the operation, every call to it answers with a Deprecation header giving the date it was deprecated, and a Sunset header gives the removal date once one is set.

Common questions

Question	Call
What should we fix first?	`GET .../v1/portfolio/<portfolio-id>/rank`
What would a fix change?	`POST .../v1/portfolio/<portfolio-id>/simulate`
How has the portfolio moved?	`GET .../v1/portfolio/<portfolio-id>/history`
What is the latest survey?	`GET .../v1/job?topLevel=true&jobType=INVENTORY_SURVEY,RUNTIME_SURVEY&limit=1`
What changed between two surveys?	`GET .../v1/report/compare`
Are our surveys arriving?	`GET .../v1/data-health/summary`

... stands for https://api.spicelabs.io/api/v1/project/<project-id>. The API reference describes each call’s parameters.