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:

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

Response headers

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

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' });