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
Whose memory this is. Stamped on every node in the request. Any string; a prefix like
user:, agent:, tckg: is recommended.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.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).Edges to write. Endpoints must exist in the same tenant, in this request or earlier.
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.
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
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.
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
Unique within the tenant. The same id may be written again only with a non-overlapping
valid interval.One of
entity, claim, prediction, commitment (a promise; valid_to is its deadline), factor, timeseries, episode.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.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.For
resolve. If the key is not declared yet the row is written with an undeclared_fact warning.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.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.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).Edge
Both must be nodes in the same tenant. Otherwise the edge is refused with
missing_endpoint.One of the 13 types in Concepts.
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).Verdict
How it was judged and under which rules, so someone else can reproduce it. A verdict without them is refused.
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.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
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).Rows handled with a note.
already_remembered (an identical row exists; nothing written), undeclared_fact.The instant the server learned this request. The first
as_of at which the rows are visible, unless a backfill was declared.{key: batch id} for every entry of backfills; empty when none was given. Sending the same keys again returns the same ids.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.