Kotlin SDK reference

Item	Value
Package	`com.surrealdb.kotlin.spectron`
Distribution	Bundled in `com.surrealdb:kotlin`
Models	`com.surrealdb.kotlin.spectron.model`
Sub-clients	`com.surrealdb.kotlin.spectron.ns`

The Spectron client ships inside the SurrealDB Kotlin SDK — there is no separate artifact. It is independent of the SurrealDB RPC engine and speaks Spectron's HTTP API directly.

Constructor

import com.surrealdb.kotlin.spectron.Spectron
import kotlin.time.Duration.Companion.seconds

val memory = Spectron(
    contextId = "acme-prod",
    apiKey = "sk-spec-...",
    endpoint = "https://api.spectron.example",
    timeout = 30.seconds,
    maxRetries = 3,
)

Parameter	Type	Default	Notes
`contextId`	`String`	required	The context to operate in.
`apiKey`	`String`	required	Bearer token; mutable `var`, applied on next request.
`endpoint`	`String`	required	Base URL; mutable `var`.
`timeout`	`Duration`	`30s`	Per-request timeout.
`maxRetries`	`Int`	`3`	GET-only retries.
`httpClient`	`HttpClient?`	`null`	Inject a Ktor client.
`json`	`Json`	lenient	`ignoreUnknownKeys = true`, `explicitNulls = false`.

Authentication uses the Authorization: Bearer header. Call close() to release the HTTP client.

Surface

Top-level suspend verbs on Spectron: remember, rememberMany, recall, queryContext, state, profile, reflect, forget, chat, consolidate, elaborate, inspect, audit, whoami, health.

Namespaced sub-clients:

Property	Type	Purpose
`documents`	`SpectronDocuments`	Upload, query, chunk, and manage documents (plus `documents.keywords`).
`sessions`	`SpectronSessions`	Create and drive chat sessions.
`entities`	`SpectronEntities`	List, fetch, and delete extracted entities.
`lifecycle`	`SpectronLifecycle`	Expire, decay, and `fsck` maintenance.
`traces`	`SpectronTraces`	Inspect decision traces and stats.
`principals`	`SpectronPrincipals`	List grants and grant/revoke access.
`scopes`	`SpectronScopes`	Register and manage scope nodes.
`keys`	`SpectronKeys`	Self-service API key creation and rotation.

Scopes and delegation

Scopes are hierarchical key/value slash-paths passed as a List<String>; an empty list targets the caller's default write region. Build them with scopePaths:

import com.surrealdb.kotlin.spectron.scopePaths

scopePaths(listOf("org/acme"))                 // ["org/acme"]
scopePaths(mapOf("org" to "acme"))             // ["org/acme"]
scopePaths("team" to "eng", "org" to "acme")   // ["team/eng", "org/acme"]

Every method takes an optional onBehalfOf: String?, sent as the X-Spectron-On-Behalf-Of header so a privileged caller acts as another principal.

Retries

GET requests retry on connection errors and 5xx responses with 250 ms / 500 ms / 1 s backoff, capped at maxRetries (default 3). Writes are never retried.

Errors

All failures throw a subclass of the sealed SpectronException, modelled on RFC 7807 problem details. Each carries status, title, detail, typeUri, instance, and extensions: Map<String, JsonElement>.

Exception	HTTP status
`SpectronAuthException`	401
`SpectronScopeException`	403
`SpectronNotFoundException`	404
`SpectronValidationException`	400, 422
`SpectronRateLimitException`	429 (with `retryAfter: Duration?`)
`SpectronServerException`	5xx and unmatched
`SpectronTransportException`	0 (connection or parse failure)

Models

Response and request types live under com.surrealdb.kotlin.spectron.model, all @Serializable:

Enums — QueryMode, DocumentStatus, TurnRole, MemoryCategory, InferMode, GraphEdgeKind, and others.
Facts — Triple, TripleEntity, BatchMessage, FactsResponseJson, FactsBatchResponseJson.
Documents — DocumentJson, ChunkJson, KeywordJson, QueryFilter, UploadResponse, QueryResponseJson.
Memory — ChatResponseJson, QueryMemoryResponseJson, ContextQueryResponseJson, StateResponseJson, ProfileResponseJson.
Governance — PrincipalJson, EffectiveGrantsJson, WhoamiResponse, ScopeNodeJson, AuditRowJson.
Maintenance — ConsolidateResponseJson, ElaborateResponseJson, InspectResponseJson, FsckReportJson.
Keys — MintedKey (secret returned once), KeyDetail.

User guide

→ Kotlin SDK