Sign in

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

post/api/v1/{context_id}/facts

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

Changed in 4 of the 5 revisions of this API.36

  • 9f15987130673See the full diff
    • ○

      added the new optional request property addressees

      new-optional-request-property

    • ○

      added the non-success response with the status 503

      response-non-success-status-added

    • ○

      added the required property extraction/oneOf[ExtractionResultJson]/actions to the response with the 200 status

      response-required-property-added

  • 52b41ab517b61See the full diff
    • ○

      added the new optional request property observed_at

      new-optional-request-property

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 6ad06b1fefc411See the full diff
    • ●

      removed the request property scope

      request-property-removed

    • ○

      added the new optional request property scopes

      new-optional-request-property

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 741d58b9ef8921See the full diff
    • ●

      removed the request property observed_at

      request-property-removed

    • ●

      removed the request property scopes

      request-property-removed

    • ○

      added the new optional request property scope

      new-optional-request-property

    This revision also has 15 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog