Result types
Pagination follows the shared Pagination and truncation contract (D154).
This page lists every shape the HTTP API returns, and the request bodies that
have a name. Field names are exactly as they appear on the wire. The same
models exist in Python as remember.models.<Name> (the most used are also
exported from remember); the remember client validates every response
against them.
The shapes group into five families:
| Family | Types | Returned by |
|---|
| Envelope | Envelope and its parts | Every read route except SQL queries, readiness, documents and deployment info; three of the four assured operations. |
| Context bundle | ContextBundle/v2 | combined_context. |
| Query result | QueryResult/v1 | POST /query/sql, POST /query/sql/explain, POST /query/saved/{namespace}/{name}/run. |
| Write and readiness | IngestedVersion, PipelineReadinessReport, DocumentPage | POST /ingest, POST /readiness, GET /documents. |
| Documents | Documents, Effective periods, Sections and references | POST /documents/search, DELETE /documents/{doc_id}, the effective-period and reference routes, section_history, document_references. |
| Deployment | ToolDescriptor, DeploymentBuildInfo | GET /operations, GET /deployment. |
Conventions
- Required and nullable. "Nullable" means the field is present and may be
null. Fields with a default are always present in responses.
- Arrays. Array fields are always present; an empty result is
[].
- Unknown fields. Every model forbids fields it does not declare, so the
remember client rejects a response with an unexpected key.
Timestamps
Timestamps in results are ISO 8601 strings in UTC. Fields typed
"UTC date-time" below are checked to have an offset of exactly zero.
Warning
Send timestamps to GET /lookup/relations (valid_at) and to the graph
routes (valid_at, believed_at) in UTC, with Z or +00:00. A
timestamp with no offset or another offset is refused with 422 and a
validation list naming the field; it is not converted. The assured
operations' time object converts any offset to UTC for you.
Envelope
The result of every read that is not a SQL query: the answer plus its own
account of what kind of answer it is, when it was true, how fresh it is,
whether it was capped, and, when the answer is "no", which kind of no.
Which fields a route fills depends on the route; the rest stay empty. No HTTP
route in this release fills ranking, changes, aggregate or pages.
| Field | Type | Contents |
|---|
grain | Grain | What kind of truth the result is. |
temporal_scope | TemporalScope | The time the answer applies to. |
entities | array of EntityCandidate | Resolve candidates. |
facts | array of FactResult | Relations and observations. |
evidence | array of EvidenceResult | Claims. |
fact_evidence | array of FactEvidence | Which claim supports or contradicts which fact. |
evidence_totals | array of EvidenceTotal | Exact evidence counts per fact and stance. |
chunks | array of ChunkEvidenceResult | Source passages. |
sources | array of SourceRecord | Documents. |
transcript | array of TranscriptEntry | Decision history. |
nodes | array of GraphNode | Entities (or documents) a traversal reached. |
paths | array of GraphPath | Whole paths. |
edges | array of GraphEdge | Relations (or citations) traversed. |
ranking | array of RankedItem | A fused or reranked order. |
changes | array of ChangeRecord | A change feed. |
aggregate | AggregateReport, nullable | An enumerated aggregate. |
pages | array of PageRef | Compiled pages. |
freshness | Freshness | How current the answer's sources are. |
truncation | Truncation, nullable | Present when a cap applied or the route always discloses one. |
next_cursor | string, nullable | Browse-page cursor; null exactly at the end. Used by graph neighborhood and browse-mode lookups. |
dropped_by_hydration | integer | Candidates that were nominated but no longer held when re-read. Default 0. |
excluded_unstamped | integer ≥ 0 | Items left out because they carry no usable time. Default 0. |
negative | Negative, nullable | Set when the answer is a typed "no". |
Which fields each route fills:
| Route or operation | Grain | Fields |
|---|
GET /resolve, resolve_entity | fact | entities, truncation, negative |
GET /lookup/relations, GET /lookup/observations | fact | facts, next_cursor (browse), truncation, dropped_by_hydration, negative |
GET /hydrate/relation/{relation_id} | composite | facts, evidence, sources, negative |
GET /transcript/relation/{relation_id} | composite | transcript, truncation, negative |
| Search routes | evidence | evidence or chunks, dropped_by_hydration, negative |
| Adjacent chunks | evidence | chunks, dropped_by_hydration, negative |
| Graph neighborhood | fact | nodes, paths, edges, next_cursor, truncation, negative |
| Other graph routes | fact | nodes, paths, edges, truncation, negative |
claims_and_sources_context | evidence | evidence, chunks, truncation, dropped_by_hydration, negative |
facts_context | fact | facts, evidence, fact_evidence, evidence_totals, nodes, truncation, dropped_by_hydration, negative |
Grain
| Value | Meaning |
|---|
fact | What the memory holds true (relations, observations, entities, the graph). |
evidence | What sources said (claims, chunks). Not a statement of truth. |
compiled | A compiled page. Not returned by any HTTP route in this release. |
composite | A fact together with the evidence and sources behind it, or a decision history. |
TemporalScope
One of five shapes, told apart by mode. Every shape carries
evaluated_at (when the read ran), believed_at (the memory's knowledge it
read from) and identity_regime.
mode | Extra fields | Used by |
|---|
current | none | Most reads; time: {"mode": "current"}. |
at | at (UTC date-time) | time: {"mode": "at"}; lookups with valid_at. |
overlap | from, to (UTC date-times, to ≥ from) | time: {"mode": "overlap"}. |
history | none | time: {"mode": "history"}. |
as_of | valid_at (UTC date-time) | Graph routes; names both clocks. |
| Field | Type |
|---|
mode | string, as above |
evaluated_at | UTC date-time |
believed_at | UTC date-time |
identity_regime | IdentityRegime, default current |
IdentityRegime
| Value | Meaning |
|---|
current | Entities are identified as they are today (today's aliases and merges), even for a past instant. Every HTTP route uses this. |
as_of | Entities are identified as they stood at the queried instant. |
EntityCandidate
| Field | Type | Contents |
|---|
entity_id | UUID | |
canonical_name | string | |
tier | string | T0 exact alias, T1 trigram, T2 phonetic, T3 embedding. |
context_hits | integer | Current relations linking this candidate to the context_entity_ids you sent. Default 0. |
FactResult
One relation or observation.
| Field | Type | Contents |
|---|
fact_id | UUID | The relation or observation id. |
kind | string | relation or observation. |
label | string | Human-readable statement of the fact. |
evidence_count | integer | Claims supporting it. |
validity | Validity | |
temporal_match | TemporalMatch | Default possible. |
contradiction_group | UUID, nullable | The contradiction group it belongs to. |
contradiction | Contradiction, nullable | The other sides, when the group is live. |
support | FactSupport | Default current. |
Validity
| Field | Type | Contents |
|---|
valid_from | UTC date-time, nullable | When it became true; null when unknown. |
valid_until | UTC date-time, nullable | When it stopped being true; null when open or unknown. |
valid_precision | ClaimValidPrecision | Default unknown. |
ingested_at | UTC date-time | When the memory learned it. |
invalidated_at | UTC date-time, nullable | When the memory stopped believing it. |
ClaimValidPrecision
How exact a validity window is: unknown, instant, day, month,
quarter, year, open (known start, still ongoing).
TemporalMatch
| Value | Meaning |
|---|
confirmed | The fact's validity certainly matches the requested time. |
possible | It may match; for example, a bound is unknown. |
FactSupport
| Value | Meaning |
|---|
current | At least one source still asserts it. |
withdrawn | Every source that asserted it has stopped. The fact is still returned, flagged. |
Contradiction
A fact's live contradiction, returned with all its sides up to a cap.
| Field | Type | Contents |
|---|
group_id | UUID | |
co_members | array of CoMember | The other sides, up to 25 inline. |
returned | integer ≥ 0 | Sides returned. |
total | integer ≥ 0 | Sides that exist. When returned is less than total, the cap applied; co-member paging is out of scope. |
CoMember
| Field | Type | Contents |
|---|
fact_id | UUID | |
label | string | |
evidence_count | integer | |
validity | Validity | |
in_documents_filter | boolean | Only on a read with a documents filter: whether this side has live support from a matching document. Absent otherwise. |
EvidenceResult
One claim with its provenance.
| Field | Type | Contents |
|---|
claim_id | UUID | |
doc_id | UUID | The document it came from. |
chunk_id | UUID | The chunk it was extracted from. |
claim_text | string | The claim, rewritten to stand alone. |
source_span | string | The source text it came from. |
char_start | integer | Start offset of the span in the converted Markdown of its representation. |
char_end | integer | End offset. |
evidence_spans | array of EvidenceSpan | Every range of that chunk's representation that supports the claim. |
is_attributed | boolean | The source reports someone else's statement ("Dana said …"). |
is_current_testimony | boolean | The claim still comes from a current version of its source. |
asserted_at | UTC date-time, nullable | When the source made the statement. Relative phrases in claim_text are relative to this. |
claim_valid_from | UTC date-time, nullable | Start of when the claim says it was true, as the source put it. null when precision is unknown. |
claim_valid_until | UTC date-time, nullable | End of that window; null when open or unknown. |
claim_valid_precision | string | instant, day, month, quarter, year, open or unknown. Default unknown. |
claim_valid_kind | string, nullable | What the window describes: event_time (when an event happened), effective_period or proposition_validity (when a state was true), measurement_period (the period a figure covers). |
document_title | string, nullable | |
source_kind | string, nullable | |
corroboration_count | integer ≥ 1, nullable | Claims with identical text grouped under this one (claims_and_sources_context). |
grouped_claim_ids | array of UUID | The ids of the grouped claims. |
version_id | UUID, nullable | Set when the claim's document has declared effective periods and the read had a time scope: the selected version that chunk_id and the offsets above belong to. |
representation_id | UUID, nullable | The converted reading of that version. |
effective | array of EffectiveInterval | That version's in-force intervals. Empty for documents without declared periods. |
occurrences | array of ClaimOccurrence | One per selected version that carries the claim, earliest period first. The first is the one the fields above describe. Empty for documents without declared periods. |
Without those fields set, chunk_id and the offsets are where the claim was
first extracted. With them, they are where the claim occurs in a version in
force for the scope; see
Reading text as of a date.
ClaimOccurrence
Where a claim occurs in one selected version.
| Field | Type |
|---|
chunk_id | UUID |
version_id | UUID |
representation_id | UUID |
char_start, char_end | integer |
evidence_spans | array of EvidenceSpan |
source_locators | JSON, nullable |
effective | array of EffectiveInterval |
served_version | boolean, default true: whether version_id is the document's served version |
EvidenceSpan
| Field | Type | Contents |
|---|
char_start | integer ≥ 0 | Start of a half-open range. |
char_end | integer ≥ 0 | End; always greater than char_start. |
FactEvidence
| Field | Type | Contents |
|---|
fact_kind | relation | observation | |
fact_id | UUID | |
claim_id | UUID | |
stance | supports | contradicts | |
in_documents_filter | boolean | Only on a read with a documents filter: whether the claim's document matches it. Supporting claims always do; contradicting claims may come from any document. Absent otherwise. |
EvidenceTotal
| Field | Type | Contents |
|---|
fact_kind | relation | observation | |
fact_id | UUID | |
stance | supports | contradicts | |
returned | integer ≥ 0 | Claims of this stance in the result. |
total | integer ≥ 0 | Claims of this stance that exist, counted once per document, across the whole deployment. Never less than returned. |
in_documents_filter_total | integer ≥ 0 | Only on a read with a documents filter: how many of those documents match it. Absent otherwise. |
ChunkEvidenceResult
One source passage.
| Field | Type | Contents |
|---|
chunk_id | UUID | |
doc_id | UUID | |
version_id | UUID | |
representation_id | UUID | The converted reading of the version the offsets refer to. |
chunk_text | string | |
context_prefix | string, nullable | Generated orientation text for the chunk, when one exists. Not evidence. |
char_start | integer | Offsets in the representation's Markdown. |
char_end | integer | |
section_role | string, nullable | The role of the section it sits in (body, abstract, references, …). |
document_title | string, nullable | |
source_kind | string | |
source_modified_at | UTC date-time, nullable | |
published_at | UTC date-time, nullable | |
effective | array of EffectiveInterval | The version's in-force intervals, when its document has declared effective periods. |
served_version | boolean | Whether version_id is the document's served version (its newest processed one). Default true. |
EffectiveInterval
One interval during which a version is in force.
| Field | Type | Contents |
|---|
from | date-time, nullable | Start, included. null is unbounded. |
until | date-time, nullable | End, excluded. null is open. |
until_declared | boolean | true when the end was declared; false when it is the next declared start, or open. Default false. |
SourceRecord
One document.
| Field | Type | Contents |
|---|
doc_id | UUID | |
title | string, nullable | |
source_kind | string | |
markdown_uri | string, nullable | Where the converted Markdown is stored. |
mention_count | integer ≥ 0, nullable | |
first_mentioned_at | UTC date-time, nullable | |
last_mentioned_at | UTC date-time, nullable | |
TranscriptEntry
One recorded decision.
| Field | Type | Contents |
|---|
subject_kind | string | relation, observation, entity or k_page. |
outcome | string | What was decided. |
method | string | How it was decided. |
confidence | number, nullable | |
related_id | UUID, nullable | The counterpart: the other fact in a supersession, the entity absorbed in a merge. |
decided_by | string | |
decided_at | UTC date-time | |
features | object, nullable | The inputs the decision recorded. |
GraphNode
| Field | Type | Contents |
|---|
entity_id | UUID | The entity, or on citation paths the document. |
name | string | Canonical name, or document title. |
hops | integer ≥ 0 | Distance from the start. |
GraphEdge
| Field | Type | Contents |
|---|
relation_id | UUID | The relation, or on citation paths the cross-reference. |
subject_id | UUID | |
object_id | UUID | |
predicate | string | On citation paths, the kind of reference. |
fact | string, nullable | The relation's label, or the citation's context. |
evidence_count | integer | 0 on citation paths. |
valid_from | UTC date-time, nullable | |
valid_until | UTC date-time, nullable | |
valid_precision | ClaimValidPrecision | Default unknown. |
ingested_at | UTC date-time, nullable | |
invalidated_at | UTC date-time, nullable | |
support | FactSupport | Default current. |
bindings | array of string | On citation paths, the distinct bindings of the references the edge merges, sorted: floating (the cited document's versions in force when read), pinned (one named version). Empty on entity edges. |
source_labels | array of string | On citation paths, the distinct caller-supplied source_label values of the merged references, sorted and verbatim; empty when none has one, and on entity edges. |
GraphPath
A path is returned whole or not at all.
| Field | Type | Contents |
|---|
length | integer ≥ 1 | Number of edges. |
nodes | array of GraphNode, at least 2 | In order. |
edges | array of GraphEdge, at least 1 | In order. |
RankedItem
| Field | Type |
|---|
item_id | UUID |
score | number |
signals | object of string to number |
ChangeRecord
| Field | Type | Contents |
|---|
kind | string | relation, observation, claim or page. |
change | string | new, invalidated, capped or recompiled. |
id | UUID | |
label | string, nullable | |
at | UTC date-time | |
AggregateReport
| Field | Type |
|---|
form | string |
buckets | array of AggregateBucket |
total | integer ≥ 0 |
possible_total | integer ≥ 0, default 0 |
bounded_by | string, nullable |
AggregateBucket
| Field | Type |
|---|
key | string, nullable |
count | integer ≥ 0 |
possible_count | integer ≥ 0, default 0 |
entity_id | UUID, nullable |
| Field | Type |
|---|
artifact_id | UUID |
page_kind | string |
git_path | string, nullable |
page_summary | string, nullable |
last_compiled_at | UTC date-time, nullable |
status | string |
stale | boolean, default false |
open_review_flags | integer ≥ 0, default 0 |
redaction_required | boolean, default false |
Freshness
| Field | Type | Contents |
|---|
pg_live_ts | UTC date-time | The database time the answer was read at. |
p1_written_inline | boolean | The search index is written in the same step as the database. Default true. |
p1_believed_at_horizon | UTC date-time, nullable | The oldest believed_at the search index can answer; null means unbounded. |
k | KFreshness, nullable | Present only when the answer used a compiled page. |
scope_pending | ScopePending, nullable | Time-scoped text reads only: documents whose version in force for the scope is still being processed. |
ScopePending
| Field | Type | Contents |
|---|
doc_ids | array of UUID | At most 50 of the documents. |
count | integer ≥ 0 | How many there are. |
complete | boolean, default true | false when the check that finds these documents stopped on a work limit; count is then a lower bound. |
KFreshness
| Field | Type |
|---|
compiled_at | UTC date-time, nullable |
stale | boolean, default false |
open_flags | integer ≥ 0, default 0 |
Truncation
A cap is never silent: when one applies, this block says so.
| Field | Type | Contents |
|---|
truncated | boolean | More existed than was returned. |
returned | integer ≥ 0 | Items returned. |
estimated_total | integer ≥ 0 | Items seen before the cap. |
total_is_exact | boolean | false when the count itself hit a cap. Default true. |
reason | string, nullable | Which cap applied, when known: resolve_candidate_limit, lookup_k_limit, result_budget, expansion_budget, frontier_budget, time_budget, depth_budget; for a search channel that stopped early, p1_work_budget, p1_deadline or p1_ann_scan_bound (more matching results may exist). Follow-up paging uses Envelope.next_cursor, not a field here. |
Negative
A typed "no". Each kind asks for a different reaction.
| Field | Type |
|---|
kind | NegativeKind |
explanation | string, at least 1 character |
workaround | string, nullable |
NegativeKind
| Value | Meaning | What to do |
|---|
unknown_entity | The name or id is not known (or no longer exists). | Resolve the name again, check spelling, or search claims and chunks. |
known_empty | The thing exists, and nothing matches. | Treat it as a real "none"; broaden the query if you expected results. |
boundary | The memory could not answer within a limit: an index not published, a graph not ready, a time budget spent. | Do not treat it as "none". Retry, or use a direct route. |
Forgotten content is indistinguishable from content that never existed: it
shows up as unknown_entity or known_empty.
ContextBundle/v2
The result of combined_context: two complete envelopes side by side.
| Field | Type | Contents |
|---|
contract | string | Always ContextBundle/v2. |
claims_and_sources | Envelope | Always grain evidence. |
facts | Envelope | Always grain fact. |
QueryResult/v1
The result of every SQL statement route, whatever the outcome. It describes
where the rows came from before giving them.
| Field | Type | Contents |
|---|
contract | string | Always QueryResult/v1. |
grade | string | Always exploratory_tabular: no grain, negatives, contradiction completeness, exact totals or order are guaranteed beyond what the fields below state. |
request_id | UUID | |
deployment_id | UUID | |
surface_manifest_hash | string | The query space version the statement ran against. |
query_space_schema | string | Always memory_v1. |
query_hash | string | Hash of the normalized statement and the types (never the values) of its parameters. Empty when the statement did not parse. |
query_language | string | Always sql. |
saved_query | object of string, nullable | For a saved query: query_id, namespace, name, version, query_hash. |
referenced_views | array of string | Views the statement reads. |
referenced_functions | array of string | Functions it calls. |
source_grain_tags | array of string | The grain tags of the referenced views. |
columns | array of ResultColumn | |
rows | array of arrays | One array per row, values in column order. |
returned_row_count | integer ≥ 0 | |
returned_byte_count | integer ≥ 0 | JSON-encoded size of the returned rows. |
limits | ResultLimits | The caps this statement ran under. |
truncated | boolean | |
truncation_reason | string, nullable | row_cap, byte_cap, or a graph budget (depth_budget, expansion_budget, frontier_budget, result_budget, time_budget). |
ordered_result | boolean | The statement has a top-level ORDER BY. |
empty_result | boolean | No rows were returned (also true on every rejection or failure). |
negative_kind | null | Always null: SQL results never carry a typed negative. |
execution_started_at | date-time | |
evaluated_at | date-time, nullable | Set only when every referenced view and function answers at one instant (facts_current, graph_edges_current, contradiction_members_current, facts_as_of). |
pg_snapshot_at | date-time, nullable | The database snapshot time. |
elapsed_ms | number ≥ 0 | |
termination_reason | string | completed, rejected or failed. |
error_code | string, nullable | One of the SQL query codes. |
error_message | string, nullable | Safe to show; never raw database detail. |
warnings | array of string | For example one entry per graph function that hit a budget. |
semantic_invocations | array of SemanticInvocation | One per search function call. |
graph_invocations | array of GraphInvocation | One per graph function call. |
ResultColumn
| Field | Type | Contents |
|---|
name | string | |
type | string | The PostgreSQL type name (text, uuid, bigint, timestamp with time zone, …). |
nullable | boolean | Always true: PostgreSQL does not report nullability for computed columns. |
ResultLimits
| Field | Type |
|---|
row_cap | integer |
byte_cap | integer |
statement_timeout_ms | integer |
analytical_tier | boolean (always false over HTTP) |
SemanticInvocation
What one search function (semantic_*, lexical_*, fetch_chunk_bodies)
did.
| Field | Type | Contents |
|---|
function | string | |
nominated | integer | Candidates the index returned. |
confirmed | integer | Candidates that held when re-read. |
dropped_stale | integer | |
dropped_filtered | integer, default 0 | |
dropped_ambiguous | integer, default 0 | |
dropped_absent | integer, default 0 | |
dropped_body_mismatch | integer, default 0 | |
dropped_absent_current | integer, default 0 | |
dropped_absent_projection | integer, default 0 | |
dropped_hash_mismatch | integer, default 0 | |
policy_generation | string, nullable | |
embedder_generation | string, nullable | |
generation | string, nullable | |
pg_confirmed_at | date-time, nullable | |
termination_reason | string, nullable | completed, or p1_work_budget, p1_deadline or p1_ann_scan_bound when the search stopped on a work limit before it could prove it had every match. |
GraphInvocation
What one graph function did.
| Field | Type |
|---|
ordinal | integer ≥ 0 |
function | graph_neighborhood | graph_path | graph_citation_path |
truncated | boolean |
truncation_reason | depth_budget | expansion_budget | frontier_budget | result_budget | time_budget, nullable |
examined_edges | integer ≥ 0 |
returned_paths | integer ≥ 0 |
effective_depth | integer ≥ 1 |
effective_expansion_budget | integer ≥ 1 |
effective_frontier_budget | integer ≥ 1 |
effective_result_budget | integer ≥ 1 |
effective_time_budget_ms | integer ≥ 1 |
applied_valid_at | date-time, nullable |
applied_believed_at | date-time, nullable |
evaluated_at | date-time, nullable |
IngestedVersion
Returned by POST /ingest.
| Field | Type | Contents |
|---|
deployment_id | UUID | |
doc_id | UUID | The document. |
version_id | UUID | The version; pass it to POST /readiness. |
content_hash | string | SHA-256 of the bytes, hex. |
created | boolean | true for a new version; false when the bytes matched the latest version and nothing new was stored. |
mime | string, nullable | The MIME type recorded for these bytes, which conversion uses. Set by the first upload of the bytes, unless that type had no converter route and a later upload sent one that has. |
title | string, nullable | The document's title, set by its first ingest. |
versioning_mode | snapshot | living, nullable | The document's versioning mode, set by its first ingest. |
version_key | string, nullable | The version's version_key, or null when it has none. Default null. |
parked | "no_route" or null | "no_route" when the upload's conversion is parked waiting for a conversion route for its MIME type: the bytes are stored, and conversion waits until an operator adds a route if needed and runs remember ops resume-no-route, or the same bytes are sent again with a MIME type that has a route. null means only that it is not parked for no_route; read processing state from POST /readiness. |
This release's engine always sets mime, title and versioning_mode; they
are null only from an engine release that predates them.
Readiness
ReadinessRequirements
The require object of POST /readiness. All four fields are required.
| Field | Type |
|---|
pipeline | boolean |
p1 | boolean |
live_graph | boolean |
p3 | boolean |
PipelineReadinessReport
| Field | Type | Contents |
|---|
ready | boolean | Every required capability is ready. |
versions | array of VersionPipelineReadiness | One per requested version. |
capabilities | object: pipeline, p1, live_graph, p3 → CapabilityReadiness | All four, required or not. |
document_binding_generation | string, nullable | As in DeploymentBuildInfo. |
model_bindings | object of string to string | As in DeploymentBuildInfo. |
build_revision | string | As in DeploymentBuildInfo. |
VersionPipelineReadiness
| Field | Type | Contents |
|---|
version_id | UUID | |
ready | boolean | Every stage is succeeded or skipped and finished. |
stages | array of PipelineStageReadiness | One per expected stage. |
PipelineStageReadiness
| Field | Type | Contents |
|---|
stage | string | The pipeline stage. |
component_version | string | The version of that stage's component the deployment expects. |
status | string | missing, pending, running, succeeded, failed, dead_letter, skipped. |
finished_at | date-time, nullable | |
defer_reason | string, nullable | Why a pending or failed stage waits: no_route (no converter for the file's type), admission (a metered deployment waiting for its control plane's approval), budget (a spend budget is used up), scheduled (due later), retry_backoff (a failed stage waiting for its next attempt). null for any other status, and for pending work that is simply queued. |
missing means no work for that stage and component version exists yet.
failed may be retried by the pipeline; dead_letter will not be.
CapabilityReadiness
| Field | Type | Contents |
|---|
required | boolean | You asked for it. |
ready | boolean | |
checked_at | date-time | |
reason | string | ready, or why not (see Ingest). |
version | string, nullable | p3: the export digest for one ready requested document; null for multiple documents or incomplete publication. |
built_at | date-time, nullable | Null for the live corpus, which has no global snapshot build time. |
published_at | date-time, nullable | Null for the live corpus, which has no global snapshot publication time. |
Documents
DocumentPage
| Field | Type | Contents |
|---|
documents | array of DocumentSummary | |
next_cursor | string, nullable | Pass to the next request; null on the last page. |
DocumentSummary
| Field | Type | Contents |
|---|
doc_id | UUID | |
title | string, nullable | |
source_kind | string | upload for a file sent without a source identity. |
source_uri | string, nullable | The source_ref, for documents sent with one. |
first_seen_at | date-time | Never changes. |
latest | DocumentVersionSummary | The newest version that has not been deleted. |
serving | boolean | Some version of this document is ready and not deleted. |
tags | array of strings | The names of the document's tags, ordered by name ignoring letter case. Empty when it has none. |
DocumentVersionSummary
| Field | Type | Contents |
|---|
version_id | UUID | |
version_no | integer | |
status | string | ingesting, converting, structuring, ready, failed, deleted. |
ingested_at | date-time | |
error | string, nullable | Why it failed. |
A version status of ready means conversion and structuring are done. It
does not mean claims and facts have been extracted; check
readiness for that.
DocumentSearchRequest
Body of POST /documents/search.
| Field | Type | Required | Default | Constraints |
|---|
query | string, nullable | no | | 1 to 4,096 characters. |
filters | DocumentSearchFilters | no | {} | |
versions | current | all | no | current | |
time | ReadTime, nullable | no | current | Which editions of a document with declared effective periods are candidates. |
k | integer | no | 20 | Ranked results with query: 1 to 200. |
limit | integer | no | 50 | Browse page size without query: 1 to 200. |
cursor | string, nullable | no | | Only without query. |
DocumentSearchFilters
| Field | Type | Default | Contents |
|---|
family | array of strings | [] | Any listed format family. |
authors | array of strings | [] | Any listed name or address. |
recipients | array of strings | [] | Any listed name or address. |
created_from, created_to | date-time with timezone, nullable | | Inclusive range on the declared creation date. |
modified_from, modified_to | date-time with timezone, nullable | | Inclusive range on the declared modification date. |
language | string, nullable | | |
thread_ref | string, nullable | | |
doc_ids | array of UUIDs | [] | |
tags | DocumentTagFilter, nullable | | The document's current tags. |
DocumentTagFilter
Tags given by name (any letter case) or tag_id. Give at least one
non-empty list; each holds up to 32 tags and none twice. Every list given
must hold. A tag that is not registered refuses the read with unknown_tag.
| Field | Type | Default | Contents |
|---|
all | array of strings | [] | The document carries every listed tag. |
any | array of strings | [] | The document carries at least one listed tag. |
none | array of strings | [] | The document carries none of the listed tags. |
DocumentSearchPage
| Field | Type | Contents |
|---|
documents | array of DocumentSearchResult | Best first with a query; newest ingested first without one. |
next_cursor | string, nullable | The next page; always null with a query. |
truncated | boolean | Ranked results exceeded k; false for browse pages. |
as_of | date-time | The instant this search judges documents at; every page of one search shares it. |
people_matched | array of DocumentPeopleMatch | Each distinct person an authors or recipients filter matched; empty without one. |
scope_pending | ScopePending, nullable | Examined documents whose edition in force for time is still being processed. |
DocumentSearchResult
| Field | Type | Contents |
|---|
doc_id | UUID | |
version_id | UUID | The version the document was judged by. |
version_no | integer | |
status | string | That version's processing status, as in DocumentVersionSummary. |
lineage_title | string, nullable | The document's title, set by its first ingest. |
tags | array of strings | The names of the document's tags, ordered by name ignoring letter case. |
file_name | string, nullable | The file name this version was ingested under. |
title | string, nullable | The title the caller declared for this version, or the title the file declares when none was. |
source_path | string, nullable | Where the file was at its source when this version was ingested. |
p3_path | string, nullable | Relative corpus folder, only for the served selected version with a matching nullable publication marker. Null for raw-only, unpublished, updating, failed and historical results. Type/topic/title changes move it; re-resolve by doc_id or use suffix lookup. |
served_version | boolean | Whether version_id is the document's served version, independently of P3 publication. Default true. |
representation_id | UUID, nullable | The described version's converted reading; with version_id it opens exactly that version. |
effective | array of EffectiveInterval | The described version's in-force intervals, for a document with declared effective periods. |
matching_editions | array of MatchingEdition | Every candidate edition that matched, earliest period first, for a document with declared effective periods. |
family | string | The format family. |
created_at, modified_at | date-time, nullable | Dates the document declares. |
language | string, nullable | |
thread_ref | string, nullable | |
authors, recipients | array of {name, address} | Either field may be null. |
extra | object | Format-specific metadata; not filterable. |
overview | string, nullable | A summary of the whole document, when processing produced one. Orientation, not evidence. |
other_matching_version_ids | array of UUIDs | With versions: all, the document's other versions that matched. |
matched_by | array of name | content | Which part of the query matched. Empty without a query. |
score | number, nullable | The combined rank score with a query; null without one. |
MatchingEdition
| Field | Type |
|---|
version_id | UUID |
version_no | integer |
version_key | string, nullable |
representation_id | UUID, nullable |
effective | array of EffectiveInterval |
DocumentPeopleMatch
| Field | Type | Contents |
|---|
role | author | recipient | |
name | string, nullable | |
address | string, nullable | |
documents | integer | Matching documents that list this person. |
DocumentDeletion
What DELETE /documents/{doc_id}
changed. The counts describe this call only.
| Field | Type | Contents |
|---|
doc_id | UUID | The deleted document. |
deleted_at | date-time | When the document was deleted. For a call that finished a deletion another path started, when the document was first hidden. |
claims_retired | integer | Claims that stopped counting as evidence. |
relations_closed | integer | Relations closed because this document was their only support. |
observations_closed | integer | Observations closed because this document was their only support. |
Tag
One registered tag, as GET /tags
and the other tag routes return it.
| Field | Type | Contents |
|---|
tag_id | UUID | Stable identity; a rename keeps it. |
name | string | The current name, with the spelling it was declared with. Unique ignoring letter case. |
description | string | What the tag means and when to apply it. |
created_at | date-time | When the tag was registered. |
updated_at | date-time | When its name or description last changed. |
TagList
| Field | Type | Contents |
|---|
tags | array of Tag | Ordered by name, ignoring letter case. |
What POST /documents/{doc_id}/tags
left on the document.
| Field | Type | Contents |
|---|
doc_id | UUID | |
tags | array of strings | The document's tag names after the change, ordered by name ignoring letter case. |
Effective periods
One period in the body of
PUT …/effective-periods
({"periods": [EffectivePeriodInput, …]}, 0 to 1,000 items with distinct
starts).
| Field | Type | Required | Constraints |
|---|
effective_from | date-time | yes | UTC. Included. |
effective_until | date-time, nullable | no | UTC. Excluded; later than effective_from. null: until the next declared start. |
EffectivePeriodsSet
| Field | Type | Contents |
|---|
doc_id | UUID | |
version_id | UUID | |
periods | array of DeclaredEffectivePeriod | The version's periods after the call, by start. |
declared | integer ≥ 0 | Periods this call added. |
retracted | integer ≥ 0 | Periods this call withdrew. |
DeclaredEffectivePeriod
| Field | Type | Contents |
|---|
period_id | UUID | |
effective_from | date-time | As declared. |
effective_until | date-time, nullable | As declared; null means until the next declared start. |
declared_at | date-time | When the declaration was made. |
EffectiveTimeCleared
| Field | Type | Contents |
|---|
doc_id | UUID | |
retracted | integer ≥ 0 | Periods withdrawn. |
cleared_at | date-time, nullable | When the document left effective time; null when it had none. |
Sections and references
One line of the NDJSON body of
PUT …/references.
| Field | Type | Required | Default | Constraints |
|---|
kind | string | yes | | cites, links_to, attaches, replies_to, refers_to, amends, implements. |
from_section_key | string, nullable | no | | Section key syntax: 1 to 200 characters from A–Z a–z 0–9 _ . : / -. |
target | ReferenceTarget | yes | | |
binding | floating | pinned | no | floating | pinned requires target.version_key. |
change_effective_from | date-time, nullable | no | | UTC. Only for amends with change_date_known: true, where it is required. |
change_date_known | boolean, nullable | for amends | | Only for amends. |
source_label | string, nullable | no | | 1 to 200 characters. |
context | string, nullable | no | | 1 to 2,000 characters. |
ReferenceTarget
| Field | Type | Required | Constraints |
|---|
source_kind | string | yes | 1 to 128 characters. |
source_ref | string | yes | 1 to 512 characters. |
version_key | string, nullable | no | 1 to 512 characters. |
section_key | string, nullable | no | Section key syntax. |
ReferencesSet
| Field | Type | Contents |
|---|
doc_id | UUID | |
version_id | UUID | |
outcome | created | unchanged | pending_cancelled | What the call did. |
generation | ReferenceGeneration | The generation the version's intent now names. |
ReferenceGenerations
| Field | Type | Contents |
|---|
doc_id | UUID | |
version_id | UUID | |
generations | array of ReferenceGeneration | Newest first, at most 100; an active generation is always included. |
ReferenceGeneration
| Field | Type | Contents |
|---|
generation_id | UUID | |
doc_id, version_id | UUID | |
origin | supplied | extracted | |
status | pending | active | rejected | superseded | |
request_seq | integer, nullable | Supplied sets: the order of the PUT calls for this version. |
input_hash | string | Identifies the set's content. |
item_count | integer, nullable | References in the set. |
representation_id, crossref_version | nullable | Extracted generations only. |
errors | array of {item, field, reason} | Why a rejected set was rejected; item is 1-based. At most 100. |
created_at | date-time | |
activated_at | date-time, nullable | |
SectionHistoryPage
| Field | Type | Contents |
|---|
doc_id | UUID | |
section_key | string | |
periodised | boolean | The document has declared effective periods; rows are then ordered by period start, otherwise by version_no. |
rows | array of SectionHistoryRow | |
amendments | array of SectionAmendment | First page only. |
next_cursor | string, nullable | |
evaluated_at, believed_at | date-time | The instants the history was read at; a cursor keeps them. |
SectionHistoryRow
| Field | Type | Contents |
|---|
version_id | UUID | |
version_no | integer | |
version_key | string, nullable | |
effective | array of EffectiveInterval | |
status | present | absent | not_indexed | processing | |
section | SectionHistorySection, nullable | Set when status is present. |
SectionHistorySection
| Field | Type | Contents |
|---|
section_id | UUID | |
node_path | string | The section's place in the version's section tree. |
title | string, nullable | The heading, without its {#key}. |
own_content_hash | string | Hash of the section's own text, subsections excluded. |
subtree_content_hash | string | Hash of the section with its subsections. |
changed | boolean, nullable | subtree_content_hash differs from the previous row that held the key; null on the first. |
own_changed | boolean, nullable | The same for own_content_hash. |
first_chunk_ids | array of UUID | Passages holding the section's first block. |
SectionAmendment
| Field | Type |
|---|
crossref_id | UUID |
from_doc_id, from_version_id | UUID |
from_section_key | string, nullable |
source_label | string, nullable |
binding | floating | pinned |
to_version_key | string, nullable |
change_effective_from | date-time, nullable |
change_date_known | boolean |
DocumentReferencesRequest
Body of POST /documents/references.
| Field | Type | Required | Default | Constraints |
|---|
chunk_id | UUID, nullable | one of chunk_id, doc_id | | |
doc_id | UUID, nullable | one of chunk_id, doc_id | | |
section_key | string, nullable | no | | Only with doc_id. |
direction | outgoing | incoming | both | no | both | |
kinds | array of strings, nullable | no | | 1 to 7 reference kinds. |
time | ReadTime, nullable | no | current; with chunk_id, the chunk's version's in-force time up to now | |
limit | integer | no | 50 | 1 to 200. |
cursor | string, nullable | no | | |
DocumentReferencesPage
| Field | Type | Contents |
|---|
rows | array of DocumentReference | |
next_cursor | string, nullable | A short page can still carry a cursor. |
evaluated_at, believed_at | date-time | |
too_broad | object, nullable | {reason: "too_broad", descendant_keys, limit, explanation} when the section has more than limit (1,000) keyed subsections; rows is then empty. |
DocumentReference
| Field | Type | Contents |
|---|
direction | outgoing | incoming | |
crossref_id | UUID | |
kind | string | A reference kind. |
origin | supplied | extracted | |
binding | floating | pinned | |
source_label, context | string, nullable | As supplied. |
change_effective_from | date-time, nullable | amends only. |
change_date_known | boolean, nullable | amends only. |
source | object | doc_id, version_id, version_key, section_key, section_title, window (a ReferenceWindow). |
named_target | object | source_kind, source_ref, version_key, section_key, exactly as the source names them. |
status | string | resolved, target_processing, target_unavailable, target_not_in_force, section_not_in_version, section_not_indexed, pinned_version_unavailable. |
target | object, nullable | doc_id, version_id, version_key, representation_id, section_key, section_title, first_chunk_ids, effective, applies_during (a ReferenceWindow), concurrent. Only what the status allows is set; null for target_unavailable. |
ReferenceWindow
| Field | Type | Contents |
|---|
from | date-time, nullable | Included; null is unbounded. |
until | date-time, nullable | Excluded unless until_inclusive; null is unbounded. |
until_inclusive | boolean | true for a closed window, such as an instant. Default false. |
One assured operation, as GET /operations returns it.
| Field | Type | Contents |
|---|
name | string | |
description | string | |
input_schema | object | JSON Schema of the arguments. Closed (additionalProperties: false). |
result_schema | object | JSON Schema of the result. |
result_contract | string | envelope or context_bundle_v2. |
output_grain | string, nullable | fact, evidence, or null for combined_context. |
answer_intent | string | identity, claims_and_sources, facts or combined_context. |
mutates | boolean, nullable | Whether the operation changes memory. false on all four shipped operations. |
version | integer ≥ 1, nullable | |
implementation_plan_hash | string of 64 hex characters, nullable | Identifies the exact plan. |
DeploymentBuildInfo
| Field | Type | Contents |
|---|
build_revision | string | Source revision the image was built from; empty when unknown. Default "". |
model_bindings | object of string to string | Model per pipeline role. Default {}. |
document_binding_generation | string, nullable | |
tools | object of string to integer | MCP memory tool name to tool version, for every tool the deployment serves. Default {}. |
Request bodies
SearchRequest
Body of POST /search/claims and POST /search/chunks.
| Field | Type | Required | Default | Constraints |
|---|
query | string | yes | | 1 to 4,096 characters. |
k | integer | no | 10 | 1 to 400. |
channel | semantic | bm25 | no | semantic | |
documents | DocumentSearchFilters, nullable | no | | Only results found in matching document versions; returned claims still cite their origin. |
time | ReadTime, nullable | no | current | Only text in force for the scope. |
ReadTime
The time scope of a text read, chosen by mode.
mode | Other fields |
|---|
current | none |
at | at: date-time with a time zone |
overlap | from, to: date-times with a time zone, both included; to not before from |
history | none |
No other fields are accepted.
AdjacentChunksRequest
Body of POST /chunks/adjacent.
| Field | Type | Required | Default | Constraints |
|---|
chunk_id | UUID | yes | | |
window | integer | no | 1 | 1 or 2. |
The graph, readiness, SQL and saved-query bodies are described with their
routes: Graph, Ingest,
SQL queries.