API overview

Base URL

https://api.usesuo.com/1

The 1 segment is the API version. Every route in this reference is relative to this base.

Authentication

Send your key in the x-suo-key header:

curl https://api.usesuo.com/1/indexes/docs/search \
  -H "x-suo-key: suo_search_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{ "q": "quickstart" }'

There are three key types, and a route only accepts the ones with enough privilege:

Prefix	Type	Can
`suo_admin_`	admin	Everything, including settings and key management
`suo_write_`	write	Write and delete records; cannot search
`suo_search_`	search	Search only; public, index- and referrer-restricted

A scoped token (suo_scoped_…, minted by you — see Scoped tokens) is sent the same way, in x-suo-key.

Response headers

Header	Meaning
`x-suo-data-version`	The index's current data version at the time of this response
`x-suo-degraded`	Present and `true` when a read was served in a degraded mode (see Errors and limits)
`x-suo-request-id`	A unique ID for this request, worth including if you report an issue

Versioning

The API is versioned by URL segment (/1/…). A new major version would ship as /2/… while /1/… keeps working; there is no silent breaking change within a version.

Errors

Every error is JSON with a stable code:

{ "error": { "code": "rate_limited", "message": "Too many requests.", "retryAfterSeconds": 4 } }

See the full list of codes, what triggers each one, and the numeric limits behind them in Errors and limits.

Routes

Route	Method	Purpose
`/1/indexes/:index/search`	POST	Search
`/1/indexes/:index/records`	POST	Write records
`/1/indexes/:index/records/:objectID`	GET	Get a record
`/1/indexes/:index/partitions/:partition`	DELETE	Clear a partition
`/1/indexes/:index/settings`	GET, PUT	Settings
`/1/indexes`	GET	List indexes
`/1/events/click`	POST	Click events
`/1/tasks/:taskId`	GET	Tasks
`/1/health`	GET	Health

The TypeScript SDK

Everything here is also available typed, generated from the same contract:

import { createSuoClient } from '@suo/client';

const client = createSuoClient({ host: 'https://api.usesuo.com', apiKey: process.env.SUO_SEARCH_KEY });
const results = await client.search('docs', { q: 'quickstart' });