Sign In

Quickstarts

Surrealist dashboard quickstart

Create a Spectron context in Surrealist, try the Playground, inspect memories, add knowledge, and call the HTTP API.

Spectron Contexts live in Surrealist beside your SurrealDB Cloud instances. This page is a UI-first tour – Playground, Memories, Knowledge, and API keys – before you reach for an SDK or the REST API.

How to find your contexts

Your contexts live inside the Surrealist dashboard right next to your SurrealDB Cloud instances and are thus visible the moment you select your organisation from the front menu.

To create your first context, choose Create context, give it a name, and select a region where it will be deployed.

Adding conversational knowledge

The easiest way to begin experimenting with a context is by opening up the Playground. This allows you to chat with the agent and watch as Experiential memories are formed. You will be able to see a stream of new memories, along with retrieved memories that show what has been recalled by the agent as you chat.

Viewing memories

Once your chat is done, open Memories from the sidebar, where you can inspect the memory graph built from your conversation with the agent.

Adding knowledge

From the sidebar, open Knowledge to go beyond chat-only data and add Authoritative pillar sources (documents, policies, and structured files the agent should treat as curated). Inside this view you will see the kinds of sources you can plug in, for example:

  • PDF

  • Markdown

  • JSON

  • Documents

  • Web pages

  • Images

  • Audio

  • Media

If you don't have any knowledge sources offhand that you'd like to add, try copying this sample mini dataset in JSON format containing some information on various musical instruments.

{
  "instruments": [
    {
      "id": "violin",
      "name": "Violin",
      "family": "Strings",
      "type": "Bowed string",
      "size": "Small",
      "range": "G3–A7",
      "origin": "Italy",
      "typical_usage": ["Orchestra", "Chamber music", "Solo"],
      "related_instruments": ["viola", "cello"],
      "description": "A high-pitched string instrument played with a bow, known for its expressive tone."
    },
    {
      "id": "cello",
      "name": "Cello",
      "family": "Strings",
      "type": "Bowed string",
      "size": "Large",
      "range": "C2–A5",
      "origin": "Italy",
      "typical_usage": ["Orchestra", "Chamber music", "Solo"],
      "related_instruments": ["violin", "double_bass"],
      "description": "A deep-toned string instrument played seated, valued for its rich and warm sound."
    },
    {
      "id": "flute",
      "name": "Flute",
      "family": "Woodwinds",
      "type": "Aerophone",
      "size": "Small",
      "range": "C4–C7",
      "origin": "Global",
      "typical_usage": ["Orchestra", "Solo", "Band"],
      "related_instruments": ["piccolo", "clarinet"],
      "description": "A high-pitched woodwind instrument that produces sound from air blown across an opening."
    },
    {
      "id": "trumpet",
      "name": "Trumpet",
      "family": "Brass",
      "type": "Lip-vibrated",
      "size": "Medium",
      "range": "F#3–D6",
      "origin": "Ancient civilisations",
      "typical_usage": ["Orchestra", "Jazz", "Band"],
      "related_instruments": ["trombone", "horn"],
      "description": "A bright and powerful brass instrument commonly used for fanfares and melodies."
    },
    {
      "id": "piano",
      "name": "Piano",
      "family": "Keyboard",
      "type": "Hammered string",
      "size": "Large",
      "range": "A0–C8",
      "origin": "Italy",
      "typical_usage": ["Solo", "Accompaniment", "Composition"],
      "related_instruments": ["harpsichord"],
      "description": "A versatile keyboard instrument capable of playing melody and harmony simultaneously."
    },
    {
      "id": "guitar",
      "name": "Guitar",
      "family": "Strings",
      "type": "Plucked string",
      "size": "Medium",
      "range": "E2–E6",
      "origin": "Spain",
      "typical_usage": ["Solo", "Band", "Accompaniment"],
      "related_instruments": ["bass_guitar", "ukulele"],
      "description": "A popular string instrument used across many genres, played by plucking or strumming."
    },
    {
      "id": "drum_kit",
      "name": "Drum Kit",
      "family": "Percussion",
      "type": "Membranophone",
      "size": "Large",
      "range": "Varies",
      "origin": "Global",
      "typical_usage": ["Band", "Jazz", "Rock"],
      "related_instruments": ["snare_drum", "cymbals"],
      "description": "A collection of percussion instruments played together to provide rhythm."
    },
    {
      "id": "harp",
      "name": "Harp",
      "family": "Strings",
      "type": "Plucked string",
      "size": "Large",
      "range": "C1–G7",
      "origin": "Ancient civilisations",
      "typical_usage": ["Orchestra", "Solo"],
      "related_instruments": ["lyre"],
      "description": "A large string instrument with strings stretched vertically, played by plucking."
    }
  ]
}

API keys

To call Spectron outside the Surrealist UI, open API keys. There you will see your Spectron base URL, your Context ID (for example 06eqs1luktt4d505nfchtdrfmo), and controls to create end-user keys. Keys are shown once when created – copy them straight into a secret store.

The page includes copy-ready snippets (cURL, JavaScript, Python, Rust, and others). Some snippets label the header Token; the HTTP API itself expects API-KEY as documented in the REST API.

For request paths and payloads (sessions, turns, recall, knowledge), follow the Hosted quickstart and the REST API reference so your calls match the current wire format.

# Example: create a session (paths and bodies vary by operation – see REST API)
curl -X POST "https://<host>/api/v1/<context_id>/sessions" \
  -H "API-KEY: sk-ctx-..." \
  -H "Content-Type: application/json" \
  -d '{"scope":{"user":"alice"},"metadata":{}}'

Next steps

Was this page helpful?

Previous

Spectron glossary

Next

Hosted quickstart