REST API

Query Sensorhub over HTTPS with JSON. Every endpoint returns only data the authenticated account can access.

OpenAPI JSON OpenAPI YAML

Authentication

There are two ways to authenticate:

• OAuth (Claude.ai, Claude Desktop, ChatGPT). Add Sensorhub as a connector, sign in, and pick one project or all projects to share. No key is needed.
• API key (Claude Code, Cursor, scripts). Create a key in the MCP section of a project, or an all-projects key on the workspace MCP page in Sensorhub, and send Authorization: Bearer sk_sh_....

A project key or single-project connection covers one project. An all-projects key or connection is workspace-wide: it reaches every project in the workspace, including new ones, and only members with access to every project can create one. API access is not available on Trial or Basic plans. A key follows the current access of the person who created it: if their access to a project is removed, so is the key's.

Some collections and reports need Perception enabled on the project. They are marked Requires Perception in this reference.

The older /api/v1/products/... endpoints are deprecated and stop working on 10 April 2027. Use /api/v1/query and the named reads instead.

Quick start

curl -X POST "https://app.sensorhub.ai/api/v1/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "sql": "SELECT id, name, plan FROM workspaces ORDER BY id ASC LIMIT 25"
}
JSON

Responses contain rows and meta. meta.hasMore tells you whether more rows exist; page with OFFSET or, where supported, the signed meta.nextCursor.

Endpoints

Rate limits and quotas

Limits are per workspace and shared by MCP and the REST API.

• Queries: Pro 60/min, 3,000/day; Agency 120/min, 9,000/day; Enterprise 180/min, 15,000/day
• Reports and reads: Pro 60/min, 1,500/day; Agency 120/min, 4,500/day; Enterprise 180/min, 7,500/day

Other plans with API access have their own limits.

A query costs 1 unit when it is admitted, plus 1 unit for each started block of 100 rows it returns, so a 1-row result costs 2 units. A query over a view that computes aggregates (COUNT, SUM and similar) adds 2 units, grouped or not. Validating a query without running it (preflight) costs 1 unit. Each report lists its own cost. When a limit is reached the API returns 429; wait before retrying.

Collections

Views

Reports and reads

Errors

Errors return a JSON body with a stable code, a message and, where useful, details such as suggested field names.