Developer docs

Open Rill → Developers, give your key a name (e.g. “automation script”), and press Create. The raw key is shown on screen exactly once — copy it before you navigate away.

Keys look like rk_live_a1b2c3d4e5f6…. Each is scoped to one user (you). Treat them like passwords: keep them in env vars, never in client-side bundles.

API key creation requires the Confluence tier. Use the key in any client (Node, Python, curl) by passing it as theX-Rill-API-Key header.

Hitting a limit returns 429 Too Many Requests. Back off and retry. Going over a paid-tier gate returns 402 Payment Required with a JSON body describing the required tier.

The simplest call — add a text capture to the user's corpus.

curl -X POST https://api.hellorill.com/entries \
  -H "X-Rill-API-Key: rk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"transcript":"Revisit the Q3 plan tomorrow morning."}'

With the SDK:

import { RillClient } from '@rill/sdk';

const client = new RillClient({ apiKey: process.env.RILL_API_KEY! });

const entry = await client.entries.create({
  transcript: 'Revisit the Q3 plan tomorrow morning.',
  sourceKind: 'my-automation',
});

console.log(entry.id);

For long answers, stream — citations land in ~400 ms, then tokens arrive as the synthesizer writes them.

for await (const ev of client.recall.askStream({ query: 'what was I thinking about Q3?' })) {
  if (ev.kind === 'citations') {
    ui.showCards(ev.citations);
  } else if (ev.kind === 'delta') {
    process.stdout.write(ev.text);
  } else if (ev.kind === 'done') {
    save(ev.answer);
  }
}

The non-streaming variant returns the full answer in one shot:client.recall.ask('…').

The corpus is naturally organised in two cross-cutting lenses:

• Stacks — by source kind (twitter, gmail, voice, youtube…). GET /me/stacks returns counts and date bounds per stack.
• Channels — by person. GET /me/channels returns the people mentioned in at least 5 captures (configurable via ?minMentions=), ranked by mention count.

Recall calls can be narrowed to either lens:

// Only my Twitter captures
await client.recall.ask('what's been on my mind lately?', { stack: 'twitter' });

// Only captures mentioning Sarah
await client.recall.ask('what did Sarah and I decide?', { channel: '<person-uuid>' });

A quarterly mirror — themes, people, decisions, stats, and a synthesized narrative. GET /me/cognitive-snapshot defaults to the current quarter; pass ?quarter=2026-Q1 for a specific one.

const snap = await client.snapshot.get('2026-Q1');
console.log(snap.narrative);

The SDK throws typed exceptions you can catch separately:

import {
  RillAuthError,
  RillPaymentRequiredError,
  RillRateLimitError,
  RillApiError,
} from '@rill/sdk';

try {
  await client.recall.ask('…');
} catch (err) {
  if (err instanceof RillAuthError) reauth();
  else if (err instanceof RillPaymentRequiredError) upsell(err.requiredTier);
  else if (err instanceof RillRateLimitError) backoff();
  else if (err instanceof RillApiError) report(err.status, err.body);
}

A developer API key is scoped to one user — yours, when you mint it in your own settings. When you build a service that holds keys for other Rill users on their behalf, you are responsible for their data: store the keys encrypted, transmit them only over TLS, give users a revoke path, and never log raw keys.

Captures created through the API are subject to the same privacy mode the user set in Rill (Full AI, Preserve, Vault, Local-only). A capture posted by a third-party integration goes through the same classify + embed + audit pipeline as any first-party capture. The per-capture What touched this? log shows the user exactly what ran, including the originating source kind.

Need help? See the full privacy page.