Hosted quickstart

This guide takes you from a blank terminal to your first remember and recall calls against Spectron on SurrealDB Cloud. Cloud runs the Spectron data plane, SurrealDB, and object store per context — you do not provision infrastructure yourself.

Step 1 — Create a Context and API key (Surrealist)

1. Sign in to SurrealDB Cloud in Surrealist.

2. Open your organisation → Contexts (requires Spectron access on your profile).

3. Subscribe to a Spectron plan (owner) if needed, then Create context — name and region.

4. Open the context → API keys → create a key. Copy the secret immediately.

You will use:

• Host — shown as the endpoint, e.g. https://abc123.spectron.cloud… (per context, not a single global URL)

• Context ID — the context identifier

• API key — sk-ctx-… shown once at creation

Step 2 — Set environment variables

export SPECTRON_URL="https://<your-context-host>"
export SPECTRON_CONTEXT_ID="<your-context-id>"
export SPECTRON_API_KEY="sk-ctx-..."

Use the exact host from Surrealist settings or API keys — not a generic placeholder domain.

Step 2b — Register scope paths

Scoped writes require registered paths. With the CLI pointed at your context:

spectron scopes create org/acme \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"

spectron scopes create org/acme/user/alice \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"

Org admins can also register scopes through the SurrealDB Cloud API admin proxy when building custom tooling.

Step 3 — Remember a fact

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/facts" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I was just promoted to CTO.",
    "infer": "full",
    "scope": ["org/acme/user/alice"]
  }'

The response includes a nested extraction object (entities, attributes, relations, …) plus sessionId and turnId.

Step 4 — Recall

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/query" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is Alice'\''s role?",
    "scope": ["org/acme/user/alice"]
  }'

Check tier in the response — tier 1 or 2 hits avoid a full LLM synthesis pass. Use trace.traceId to fetch the full retrieval trace.

Step 5 — Optional chat

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/chat" \
  -H "Authorization: Bearer $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarise what you know about me",
    "scope": ["org/acme/user/alice"]
  }'

SDKs

Official clients: surrealdb (Python, includes Spectron / AsyncSpectron) and @surrealdb/spectron (TypeScript). Point them at endpoint: process.env.SPECTRON_URL (your context host). See Integrations.

Cloud vs self-hosted

For Docker or bare-metal deployment, see Self-hosted quickstart.

Next steps

• Spectron on SurrealDB Cloud — Cloud API vs data plane

• Surrealist dashboard quickstart — UI tour

• Sessions and turns

• Contexts and scope

• Uploading documents