Quickstart: push with the API

Use the API when your content is not a set of public pages: records behind a login, a per-user library, or anything generated by your own server. This is how Toread indexes each reader's library.

1. Create an index and a write key

From the dashboard, create an index and a write key (ingest only, cannot search). Keys are shown once — copy it now.

2. Push your first batch

curl -X POST https://api.usesuo.com/1/indexes/library/records \
  -H "x-suo-key: suo_write_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "operations": [
      { "action": "upsert", "record": { "objectID": "item-482", "title": "The gentle art of note-taking", "url": "https://example.com/read/item-482" } }
    ]
  }'

Every record needs an objectID. Everything else is your own attributes — suo does not require a fixed schema. See Write records for the full request and response shape.

3. Search it

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

4. Add partitions for per-user content

If each reader should only ever see their own records, declare a partitionKey on the index (see Partitions) and mint a scoped token per reader from your own server. The widget or SDK then searches with that token instead of a shared key.

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

const client = createSuoClient({ host: 'https://api.usesuo.com', apiKey: process.env.SUO_WRITE_KEY });

await client.records.upsert('library', [
	{
		objectID: 'item-482',
		title: 'The gentle art of note-taking',
		url: 'https://example.com/read/item-482',
	},
]);

Keeping it in sync

Push on every write to your own database: when a record is created, changes, or is deleted. Pass version as your own updatedAt so a late or out-of-order write never overwrites a newer one — see Versions and last-writer-wins.

Next: read Push app content for the full per-user partition walkthrough, or the API reference for every route.