Developer quickstart

Write context. Query it back. Inspect why.

The proposed API keeps the first successful experience small while exposing the production concepts that matter: scope, idempotency, bookmark consistency, provenance, and spend safety.

Run the simulated quickstart View the API concept

Conceptual SDK and endpoints · not connected to a production service

Activation target

Five steps, one complete loop.

Create project

Select home region and budget behavior.

Issue scoped key

Show the secret once; provide safe environment setup.

Remember an episode

Commit atomically with a source and idempotency key.

Query after bookmark

Get immediate retrieval across the recent-write window.

Inspect and cap

See provenance, watermarks, usage, and the spend ceiling.

import { Solarflare } from "@solarflaredb/sdk";

const db = new Solarflare({ apiKey: process.env.SOLARFLAREDB_KEY });

const write = await db.memory.remember({
  agent: "agent:support",
  episode: "Avery moved the launch review to Friday.",
  source: { type: "message", id: "msg_92" },
  idempotencyKey: "msg_92"
});

const context = await db.context.query({
  query: "When is Avery's launch review?",
  consistency: { after: write.bookmark },
  explain: true
});

from solarflaredb import Solarflare

client = Solarflare(api_key=os.environ["SOLARFLAREDB_KEY"])

write = client.memory.remember(
    agent="agent:support",
    episode="Avery moved the launch review to Friday.",
    source={"type": "message", "id": "msg_92"},
    idempotency_key="msg_92",
)

context = client.context.query(
    query="When is Avery's launch review?",
    after=write.bookmark,
    explain=True,
)

# Exchange the API key for a short-lived capability token
curl -X POST https://api.solarflaredb.com/v2/token/exchange \
  -H "Content-Type: application/json" \
  -d '{"apiKey":"'$SOLARFLAREDB_KEY'"}'

# Write
curl -X POST https://api.solarflaredb.com/v2/graphs/memory/mutate \
  -H "Authorization: Bearer $SOLARFLAREDB_TOKEN" \
  -H "Idempotency-Key: msg_92" \
  -H "Content-Type: application/json" \
  -d '{ "operations": [ { "operationKind": "append-event", "body": { "key": "episode:msg_92", "event": { "text": "Avery moved the launch review to Friday." } } } ] }'

# Read back at or after the returned commitToken
curl "https://api.solarflaredb.com/v2/graphs/memory/values/episode%3Amsg_92?consistencyToken=$COMMIT_TOKEN" \
  -H "Authorization: Bearer $SOLARFLAREDB_TOKEN"

Concept API

Small surface, explicit semantics.

The final API should derive from the implemented engine and OpenAPI review. These resources communicate the intended developer contract, not a promise that the current source exposes them.

Memory API

Add episodes, source metadata, attachments, observations, extraction hints, and subject scopes. Return commit bookmark and projection state.

Context API

Query by natural language and structured filters, select as-of semantics, request explanations, and control context budget.

Graph API

Create typed entities and links, traverse bounded patterns, resolve aliases, and inspect supersession or contradiction paths.

Stream API

Subscribe to authorized shapes, resume from bookmarks, inspect watermarks, and rebuild derived local projections.

Response contract

The answer includes its operating conditions.

Every context result should be usable by an application and auditable by an engineer.

Result

Structured context item, current or as-of status, confidence, valid interval, and optional assembled text.

Explanation

Exact, lexical, semantic, graph, temporal, and reranking signals plus source lineage.

Freshness

Authoritative bookmark, lexical watermark, vector watermark, and whether a recent-write overlay contributed.

Errors that help

Make consistency and cost failures actionable.

Errors should tell developers what was committed, what remains retriable, which limit applied, and whether an idempotency key can safely be reused.

Atomic validation

A rejected batch commits and bills nothing. Field errors include path, type definition, policy, and request limits.

Gap and freshness visibility

A query that cannot satisfy an after-bookmark requirement reports the lagging component and retry guidance.

Quota headers

Responses report remaining included usage, projected spend, ceiling state, and reset time without exposing cross-tenant data.

Try the entire quickstart without an account.

The console uses browser local storage and fake responses. Nothing leaves the device and no secret is real.

Open the console simulation Read integration guides