Senso
Sign inSign up

For Developers

Limits

Rate limits, pagination, and what can change in the API without warning.

What the API does when you ask for a lot, and what you can rely on staying the same.

Rate limits

There is no published rate limit on the REST API today. Two places do enforce one:

SurfaceLimit
MCP server60 requests per minute per API key, counted across every client using that key. Returns 429 with a Retry-After header
POST /org/prompts/suggestionsIts own limit, returning 429. The number is not published
Everything else is unmetered as of today. That is a fact about now, not a promise — treat 429 as possible on any endpoint, honor Retry-After when it is present, and back off exponentially when it is not.

Credits are the real budget. A call can fail with 402 long before it fails with 429, so check GET /org/credits/balance when something stops working in bulk.

Pagination

List endpoints take limit and offset. offset starts at 0.

bash
curl "https://apiv2.senso.ai/api/v1/org/tags?limit=50&offset=100" \
  -H "X-API-Key: $SENSO_API_KEY"

Defaults and maximums vary by endpoint — most default to 50 and cap at 100, but some default to 10 or 25, and a few have no cap at all. The API Reference states both for every operation. Do not assume one rule across the API.

There are no cursors. Paging with offset while data is being written can repeat or skip a row, so for a consistent snapshot of a large collection, page fast and de-duplicate on id.

Sorting exists on the analytics endpoints only, through sort and order. See Analytics.

Versioning

The API is served at /api/v1 and the published spec is version 0.2.0. The path is stable. The spec is still moving.

What you can rely on:

  • Status codes — the meaning of 401, 402, 403, 404 will not change
  • Existing field names — fields are added, not renamed in place
  • Path prefix — /api/v1 stays
What can change without notice, while the spec is below 1.0:

  • New fields appearing in responses. Parse permissively and ignore what you do not recognize
  • Error response bodies, which are not in the contract at all — see Errors
  • Endpoints marked as beta in the API reference
Pin nothing to a response shape you have not seen documented.

Sizes

ThingLimit
Files per upload call10
Upload formatsPDF, TXT, CSV, DOC, DOCX, XLS, XLSX, PPT, PPTX, HTML, JSON, XML
Markdown and plain textNot accepted as a file upload — send as text through POST /org/kb/raw or the MCP server

Next steps