Skip to main content
Two ways in. Structured: nodes and edges as they are; the server stamps captured_at and lists what it could not write in refused. Natural language: messages, each with the instant it was said or written; the engine extracts the statements as claim and prediction blocks, the people, assets and organisations as entity nodes, and the causal links the speaker actually argued as typed edges between the blocks. A request may carry both.
A block extracted from a message is asserted when the message says it was (observed_at), never when it was ingested. Add a backfill declaration when the message is from the past so the blocks are also known then, not today. Without it, a 2024 transcript ingested today is asserted in 2024 but known today, and as_of=2024-06-01 reads hide it.

Request

string
required
Whose memory this is. Stamped on every node in the request. Any string; a prefix like user:, agent:, tckg: is recommended.
object
Declares that this data was known before today. The request becomes one batch, and masking uses declared_captured_at for every row in it. Fields: declared_captured_at (timestamp), reason (string). The server records who vouches for the batch: your API key’s label, or your tenant when the key has none. Sending vouched_by or declared_by here is refused with 400 TCKG_VOUCHED_BY_SUPPLIED, and on a node, edge or verdict with refused: vouched_by_supplied (0.3.11). See Concepts.
object[]
default:"[]"
Several backfill batches in one request, each named by a key of your choosing (1 to 200 characters): [{key, declared_captured_at, reason}], at most 1000 (more is 400 TCKG_TOO_MANY_BACKFILLS). A node, edge or verdict picks one with batch: <key>; a row without batch uses backfill, or none. Keys belong to your tenant: sending the same key with the same declared_captured_at and reason again returns the batch already declared, so retrying a request whose response was lost leaves no extra batch. The same key with a different instant or reason, or from a key with another label, is 409 TCKG_BATCH_KEY_CONFLICT and nothing in the request is written. A batch key your tenant never declared refuses that row with unknown_batch. Check GET /v1/version is at least 0.3.12 first, comparing the numbers part by part (as strings, 0.3.12 sorts before 0.3.9): an older server ignores backfills and batch and writes the rows as known today (0.3.12).
Node[]
default:"[]"
Nodes to write. One request is one transaction.
Edge[]
default:"[]"
Edges to write. Endpoints must exist in the same tenant, in this request or earlier.
Verdict[]
default:"[]"
Judgements a resolver made on blocks: a prediction that came true, a claim found false. Written after the nodes, so a verdict can judge a block in the same request.
Message[]
default:"[]"
Natural language to extract from. Processed in order; each message is one episode. Extraction takes a few seconds per message and runs inside the request.

Message

string
required
The text: a transcript, a note, a conversation turn, an article.
string
required
When it was said or written (ISO 8601 date or instant). Every block extracted from it is asserted at this instant, and the extraction knows nothing after it.
string
A label for the episode. Defaults to the first words of the content.
string
Where it came from: a channel, a document, a meeting.
What comes out of a message: The same statement said again in a later message resolves onto the existing block (no duplicate); a statement the engine judges to contradict an earlier one leaves the earlier block in place and adds a SUPERSEDES edge from the newer one.

Node

string
required
Unique within the tenant. The same id may be written again only with a non-overlapping valid interval.
string
required
One of entity, claim, prediction, commitment (a promise; valid_to is its deadline), factor, timeseries, episode.
string
The text that search indexes.
string
object
Free-form. Conventions: about (the period the content is about), source, factblock_id.
timestamp
required
When the statement was made. If you only know the day, send the bare date ("2026-11-19"): it is stored as midnight UTC with asserted_at_precision: "day". A time without seconds ("2026-11-19T14:30Z") is stored as minute precision. Anything with seconds is exact.
string
How precisely asserted_at is known: year, month, day, hour or minute. asserted_at is then the start of that unit, and the statement was made at some point within it. Omit it when the time is exact, or let the written form of asserted_at set it (above); a value you send wins over the form. Any other value refuses the row with bad_precision. Stored and returned on reads and in export; it does not change which rows a read returns or their order.
timestamp
Start of the validity interval.
timestamp
End of the validity interval. Open when omitted.
string
For resolve. If the key is not declared yet the row is written with an undeclared_fact warning.
any
The value resolve returns for this candidate.
object[]
The cases this block applies to, as [{key, op, value}]; all must hold, and a block without it applies to every case. op is eq (value a string, or a non-empty list of strings meaning any of them), after or before (value an ISO 8601 date or instant). The server checks the shape only and refuses a malformed one with bad_applies_if; it does not evaluate the conditions yet. Carried on the node line of export when present.
number[]
Optional. When omitted, the hosted server computes it from statement with its model (Vertex gemini-embedding-001, 1024 dimensions), so search can find the node by meaning. A vector you send is kept as is; send one only from the same model and dimension. The vector is a search index, not content: sending the same node again with or without one is still the same node. The server embeds only the nodes a write adds: a node reported as already_remembered or refused costs no model call, so resending a bundle is cheap. The vector is filled in right after the row is written; if the model fails, the request errors, the rows are already in, and POST /v1/embeddings/fill fills them.
string
The key of one of your backfills batches (this request’s or an earlier one’s). Edges and verdicts take the same field (0.3.12).
forbidden
Sending either refuses the row with captured_at_supplied. The server owns knowledge time.

Edge

string
required
string
required
Both must be nodes in the same tenant. Otherwise the edge is refused with missing_endpoint.
string
required
One of the 13 types in Concepts.
number
0 to 1.
string
One duration: ISO 8601 ("P20D", "P1M", "PT6H") or number-unit pairs ("20 days", "10d", "1 day 6 hours"). Anything else refuses the row with lag_not_a_duration, including ranges: Postgres would read "1-2 months" as 1 year 2 months. Put ranges and words in properties (for example properties.lag_text).
string
One sentence on why.
object
Free-form.
timestamp
required
timestamp
As for nodes.

Verdict

string
required
The block judged.
string
One of hit, miss, partial, undecidable.
string
required
What was measured, as text (a return, a JSON object).
string
required
How it was judged and under which rules, so someone else can reproduce it. A verdict without them is refused.
string
Who or what judged it.
timestamp
required
When it was decided. A verdict becomes visible to reads as of its known_at: now, or the backfill instant. Sending known_at yourself is refused.
A verdict is a row, never an edit: judging a block again adds a second verdict with a later decided_at, and reads take the latest one known at as_of. To bring the verdicts of a FactBlock bundle (resolutions.jsonl) into a space, one backfill batch per day they became known, run clients/push-verdicts.py <bundle> <url> --space <space> from the tckg repository; it skips verdicts the space already has.

Response

integer
Rows written (nodes plus edges).
object[]
Rows not written. Each has the row’s ids, a stable reason, and why with the original error text. Reasons: captured_at_supplied, unknown_batch, missing_endpoint, cross_tenant, overlapping_valid (same id, overlapping valid), missing_required_field, lag_not_a_duration, unparseable_value (timestamps), bad_applies_if (a node’s applies_if is not [{key, op, value}] with a known op and a well-typed value), bad_precision (a node’s asserted_at_precision is not one of year, month, day, hour, minute).
object[]
Rows handled with a note. already_remembered (an identical row exists; nothing written), undeclared_fact.
timestamp
The instant the server learned this request. The first as_of at which the rows are visible, unless a backfill was declared.
uuid or null
The batch id when backfill was given.
object
{key: batch id} for every entry of backfills; empty when none was given. Sending the same keys again returns the same ids.
object[]
One entry per message, in order. id is the episode node. nodes lists what the message produced (id, kind, statement); existing blocks the message resolved onto appear here with their existing ids. edges lists the relations (source_id, target_id, edge_type, fact), with as saying how each was stored: edge for a typed link between two blocks, claim for a relation that became a block of its own (a statement about two entities). accepted counts them.