SUsurrealdb

POST /api/v1/{context_id}/facts

Changed on

Write a single fact. Dispatches on infer mode: full (LLM-extracted), triples (caller-supplied), preview (dry run), none (literal).

Request

Path parameters

context_idstring required

Spectron context id

Request body

addresseesstring[]

Who the turn is addressed to, as entity-surface names, when the caller knows. Grounds the second person at extraction: one addressee resolves "you"/"your" (and the ownership of reacted-to events), several ground only "we"/"us". Empty keeps extraction byte-identical to the addressee-less form. Declared by the caller, never inferred. Names are Unicode-normalized (NFC) on receipt. When consumed (the full and preview infer modes; none and triples ignore the field), each name must be name-like: at most 8 names of at most 128 characters and 8 words each, letters/digits in any script (with the combining marks scripts build names from) plus spaces and ' - . _, at least one alphanumeric character, and never the reserved alias self; requests outside these rules are rejected.

infer'full' | 'triples' | 'preview' | 'none'

Inference mode for the /facts write API.

Decides which extraction path runs and which provenance kind the reconciler tags the writes with (see the per-variant docs below).

labelsLabel[]

Descriptive labels for the persisted rows (scope-model §5). Accepted and recorded on the wire now; row-level application lands in a follow-up (cf. ScopeView — accepted but behaves as Strict).

memory_category'identity' | 'knowledge' | 'context'

Memory category classification applied during extraction.

observed_atstring nullable

Optional RFC3339 known/observed time for the written facts (backfill). When set, the facts are stamped with this created_at (known time), so as_of queries see them dated to when they were observed rather than to wall-clock ingest. None keeps the default (facts dated to ingest time).

role'user' | 'assistant' | 'system' | 'tool'

Role of a conversation turn participant.

session_idstring nullable

Existing session id to attach the turn to. When absent, the handler auto-creates a session before the write.

textstring nullable

Free-form text (used by full, preview, none). Optional only when infer = triples is supplied.

Response

chunkIdstring
mode'full' | 'triples' | 'preview' | 'none' required

Inference mode for the /facts write API.

Decides which extraction path runs and which provenance kind the reconciler tags the writes with (see the per-variant docs below).

previewboolean
sessionIdstring required
turnIdstring

Changes

  • 9f1598713067Revision changes
    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the required property ///// to the response with the status

  • 52b41ab517b6Revision changes
    • info

      added the new optional request property