RememberStackremember.dev/docs

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:

FamilyTypesReturned by
EnvelopeEnvelope and its partsEvery read route except SQL queries, readiness, documents and deployment info; three of the four assured operations.
Context bundleContextBundle/v2combined_context.
Query resultQueryResult/v1POST /query/sql, POST /query/sql/explain, POST /query/saved/{namespace}/{name}/run.
Write and readinessIngestedVersion, PipelineReadinessReport, DocumentPagePOST /ingest, POST /readiness, GET /documents.
DocumentsDocuments, Effective periods, Sections and referencesPOST /documents/search, DELETE /documents/{doc_id}, the effective-period and reference routes, section_history, document_references.
DeploymentToolDescriptor, DeploymentBuildInfoGET /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.

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.

FieldTypeContents
grainGrainWhat kind of truth the result is.
temporal_scopeTemporalScopeThe time the answer applies to.
entitiesarray of EntityCandidateResolve candidates.
factsarray of FactResultRelations and observations.
evidencearray of EvidenceResultClaims.
fact_evidencearray of FactEvidenceWhich claim supports or contradicts which fact.
evidence_totalsarray of EvidenceTotalExact evidence counts per fact and stance.
chunksarray of ChunkEvidenceResultSource passages.
sourcesarray of SourceRecordDocuments.
transcriptarray of TranscriptEntryDecision history.
nodesarray of GraphNodeEntities (or documents) a traversal reached.
pathsarray of GraphPathWhole paths.
edgesarray of GraphEdgeRelations (or citations) traversed.
rankingarray of RankedItemA fused or reranked order.
changesarray of ChangeRecordA change feed.
aggregateAggregateReport, nullableAn enumerated aggregate.
pagesarray of PageRefCompiled pages.
freshnessFreshnessHow current the answer's sources are.
truncationTruncation, nullablePresent when a cap applied or the route always discloses one.
next_cursorstring, nullableBrowse-page cursor; null exactly at the end. Used by graph neighborhood and browse-mode lookups.
dropped_by_hydrationintegerCandidates that were nominated but no longer held when re-read. Default 0.
excluded_unstampedinteger ≥ 0Items left out because they carry no usable time. Default 0.
negativeNegative, nullableSet when the answer is a typed "no".

Which fields each route fills:

Route or operationGrainFields
GET /resolve, resolve_entityfactentities, truncation, negative
GET /lookup/relations, GET /lookup/observationsfactfacts, next_cursor (browse), truncation, dropped_by_hydration, negative
GET /hydrate/relation/{relation_id}compositefacts, evidence, sources, negative
GET /transcript/relation/{relation_id}compositetranscript, truncation, negative
Search routesevidenceevidence or chunks, dropped_by_hydration, negative
Adjacent chunksevidencechunks, dropped_by_hydration, negative
Graph neighborhoodfactnodes, paths, edges, next_cursor, truncation, negative
Other graph routesfactnodes, paths, edges, truncation, negative
claims_and_sources_contextevidenceevidence, chunks, truncation, dropped_by_hydration, negative
facts_contextfactfacts, evidence, fact_evidence, evidence_totals, nodes, truncation, dropped_by_hydration, negative

Grain

ValueMeaning
factWhat the memory holds true (relations, observations, entities, the graph).
evidenceWhat sources said (claims, chunks). Not a statement of truth.
compiledA compiled page. Not returned by any HTTP route in this release.
compositeA 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.

modeExtra fieldsUsed by
currentnoneMost reads; time: {"mode": "current"}.
atat (UTC date-time)time: {"mode": "at"}; lookups with valid_at.
overlapfrom, to (UTC date-times, to ≥ from)time: {"mode": "overlap"}.
historynonetime: {"mode": "history"}.
as_ofvalid_at (UTC date-time)Graph routes; names both clocks.
FieldType
modestring, as above
evaluated_atUTC date-time
believed_atUTC date-time
identity_regimeIdentityRegime, default current

IdentityRegime

ValueMeaning
currentEntities are identified as they are today (today's aliases and merges), even for a past instant. Every HTTP route uses this.
as_ofEntities are identified as they stood at the queried instant.

EntityCandidate

FieldTypeContents
entity_idUUID
canonical_namestring
tierstringT0 exact alias, T1 trigram, T2 phonetic, T3 embedding.
context_hitsintegerCurrent relations linking this candidate to the context_entity_ids you sent. Default 0.

FactResult

One relation or observation.

FieldTypeContents
fact_idUUIDThe relation or observation id.
kindstringrelation or observation.
labelstringHuman-readable statement of the fact.
evidence_countintegerClaims supporting it.
validityValidity
temporal_matchTemporalMatchDefault possible.
contradiction_groupUUID, nullableThe contradiction group it belongs to.
contradictionContradiction, nullableThe other sides, when the group is live.
supportFactSupportDefault current.

Validity

FieldTypeContents
valid_fromUTC date-time, nullableWhen it became true; null when unknown.
valid_untilUTC date-time, nullableWhen it stopped being true; null when open or unknown.
valid_precisionClaimValidPrecisionDefault unknown.
ingested_atUTC date-timeWhen the memory learned it.
invalidated_atUTC date-time, nullableWhen the memory stopped believing it.

ClaimValidPrecision

How exact a validity window is: unknown, instant, day, month, quarter, year, open (known start, still ongoing).

TemporalMatch

ValueMeaning
confirmedThe fact's validity certainly matches the requested time.
possibleIt may match; for example, a bound is unknown.

FactSupport

ValueMeaning
currentAt least one source still asserts it.
withdrawnEvery 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.

FieldTypeContents
group_idUUID
co_membersarray of CoMemberThe other sides, up to 25 inline.
returnedinteger ≥ 0Sides returned.
totalinteger ≥ 0Sides that exist. When returned is less than total, the cap applied; co-member paging is out of scope.

CoMember

FieldTypeContents
fact_idUUID
labelstring
evidence_countinteger
validityValidity
in_documents_filterbooleanOnly 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.

FieldTypeContents
claim_idUUID
doc_idUUIDThe document it came from.
chunk_idUUIDThe chunk it was extracted from.
claim_textstringThe claim, rewritten to stand alone.
source_spanstringThe source text it came from.
char_startintegerStart offset of the span in the converted Markdown of its representation.
char_endintegerEnd offset.
evidence_spansarray of EvidenceSpanEvery range of that chunk's representation that supports the claim.
is_attributedbooleanThe source reports someone else's statement ("Dana said …").
is_current_testimonybooleanThe claim still comes from a current version of its source.
asserted_atUTC date-time, nullableWhen the source made the statement. Relative phrases in claim_text are relative to this.
claim_valid_fromUTC date-time, nullableStart of when the claim says it was true, as the source put it. null when precision is unknown.
claim_valid_untilUTC date-time, nullableEnd of that window; null when open or unknown.
claim_valid_precisionstringinstant, day, month, quarter, year, open or unknown. Default unknown.
claim_valid_kindstring, nullableWhat 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_titlestring, nullable
source_kindstring, nullable
corroboration_countinteger ≥ 1, nullableClaims with identical text grouped under this one (claims_and_sources_context).
grouped_claim_idsarray of UUIDThe ids of the grouped claims.
version_idUUID, nullableSet 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_idUUID, nullableThe converted reading of that version.
effectivearray of EffectiveIntervalThat version's in-force intervals. Empty for documents without declared periods.
occurrencesarray of ClaimOccurrenceOne 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.

FieldType
chunk_idUUID
version_idUUID
representation_idUUID
char_start, char_endinteger
evidence_spansarray of EvidenceSpan
source_locatorsJSON, nullable
effectivearray of EffectiveInterval
served_versionboolean, default true: whether version_id is the document's served version

EvidenceSpan

FieldTypeContents
char_startinteger ≥ 0Start of a half-open range.
char_endinteger ≥ 0End; always greater than char_start.

FactEvidence

FieldTypeContents
fact_kindrelation | observation
fact_idUUID
claim_idUUID
stancesupports | contradicts
in_documents_filterbooleanOnly 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

FieldTypeContents
fact_kindrelation | observation
fact_idUUID
stancesupports | contradicts
returnedinteger ≥ 0Claims of this stance in the result.
totalinteger ≥ 0Claims of this stance that exist, counted once per document, across the whole deployment. Never less than returned.
in_documents_filter_totalinteger ≥ 0Only on a read with a documents filter: how many of those documents match it. Absent otherwise.

ChunkEvidenceResult

One source passage.

FieldTypeContents
chunk_idUUID
doc_idUUID
version_idUUID
representation_idUUIDThe converted reading of the version the offsets refer to.
chunk_textstring
context_prefixstring, nullableGenerated orientation text for the chunk, when one exists. Not evidence.
char_startintegerOffsets in the representation's Markdown.
char_endinteger
section_rolestring, nullableThe role of the section it sits in (body, abstract, references, …).
document_titlestring, nullable
source_kindstring
source_modified_atUTC date-time, nullable
published_atUTC date-time, nullable
effectivearray of EffectiveIntervalThe version's in-force intervals, when its document has declared effective periods.
served_versionbooleanWhether version_id is the document's served version (its newest processed one). Default true.

EffectiveInterval

One interval during which a version is in force.

FieldTypeContents
fromdate-time, nullableStart, included. null is unbounded.
untildate-time, nullableEnd, excluded. null is open.
until_declaredbooleantrue when the end was declared; false when it is the next declared start, or open. Default false.

SourceRecord

One document.

FieldTypeContents
doc_idUUID
titlestring, nullable
source_kindstring
markdown_uristring, nullableWhere the converted Markdown is stored.
mention_countinteger ≥ 0, nullable
first_mentioned_atUTC date-time, nullable
last_mentioned_atUTC date-time, nullable

TranscriptEntry

One recorded decision.

FieldTypeContents
subject_kindstringrelation, observation, entity or k_page.
outcomestringWhat was decided.
methodstringHow it was decided.
confidencenumber, nullable
related_idUUID, nullableThe counterpart: the other fact in a supersession, the entity absorbed in a merge.
decided_bystring
decided_atUTC date-time
featuresobject, nullableThe inputs the decision recorded.

GraphNode

FieldTypeContents
entity_idUUIDThe entity, or on citation paths the document.
namestringCanonical name, or document title.
hopsinteger ≥ 0Distance from the start.

GraphEdge

FieldTypeContents
relation_idUUIDThe relation, or on citation paths the cross-reference.
subject_idUUID
object_idUUID
predicatestringOn citation paths, the kind of reference.
factstring, nullableThe relation's label, or the citation's context.
evidence_countinteger0 on citation paths.
valid_fromUTC date-time, nullable
valid_untilUTC date-time, nullable
valid_precisionClaimValidPrecisionDefault unknown.
ingested_atUTC date-time, nullable
invalidated_atUTC date-time, nullable
supportFactSupportDefault current.
bindingsarray of stringOn 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_labelsarray of stringOn 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.

FieldTypeContents
lengthinteger ≥ 1Number of edges.
nodesarray of GraphNode, at least 2In order.
edgesarray of GraphEdge, at least 1In order.

RankedItem

FieldType
item_idUUID
scorenumber
signalsobject of string to number

ChangeRecord

FieldTypeContents
kindstringrelation, observation, claim or page.
changestringnew, invalidated, capped or recompiled.
idUUID
labelstring, nullable
atUTC date-time

AggregateReport

FieldType
formstring
bucketsarray of AggregateBucket
totalinteger ≥ 0
possible_totalinteger ≥ 0, default 0
bounded_bystring, nullable

AggregateBucket

FieldType
keystring, nullable
countinteger ≥ 0
possible_countinteger ≥ 0, default 0
entity_idUUID, nullable

PageRef

FieldType
artifact_idUUID
page_kindstring
git_pathstring, nullable
page_summarystring, nullable
last_compiled_atUTC date-time, nullable
statusstring
staleboolean, default false
open_review_flagsinteger ≥ 0, default 0
redaction_requiredboolean, default false

Freshness

FieldTypeContents
pg_live_tsUTC date-timeThe database time the answer was read at.
p1_written_inlinebooleanThe search index is written in the same step as the database. Default true.
p1_believed_at_horizonUTC date-time, nullableThe oldest believed_at the search index can answer; null means unbounded.
kKFreshness, nullablePresent only when the answer used a compiled page.
scope_pendingScopePending, nullableTime-scoped text reads only: documents whose version in force for the scope is still being processed.

ScopePending

FieldTypeContents
doc_idsarray of UUIDAt most 50 of the documents.
countinteger ≥ 0How many there are.
completeboolean, default truefalse when the check that finds these documents stopped on a work limit; count is then a lower bound.

KFreshness

FieldType
compiled_atUTC date-time, nullable
staleboolean, default false
open_flagsinteger ≥ 0, default 0

Truncation

A cap is never silent: when one applies, this block says so.

FieldTypeContents
truncatedbooleanMore existed than was returned.
returnedinteger ≥ 0Items returned.
estimated_totalinteger ≥ 0Items seen before the cap.
total_is_exactbooleanfalse when the count itself hit a cap. Default true.
reasonstring, nullableWhich 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.

FieldType
kindNegativeKind
explanationstring, at least 1 character
workaroundstring, nullable

NegativeKind

ValueMeaningWhat to do
unknown_entityThe name or id is not known (or no longer exists).Resolve the name again, check spelling, or search claims and chunks.
known_emptyThe thing exists, and nothing matches.Treat it as a real "none"; broaden the query if you expected results.
boundaryThe 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.

FieldTypeContents
contractstringAlways ContextBundle/v2.
claims_and_sourcesEnvelopeAlways grain evidence.
factsEnvelopeAlways grain fact.

QueryResult/v1

The result of every SQL statement route, whatever the outcome. It describes where the rows came from before giving them.

FieldTypeContents
contractstringAlways QueryResult/v1.
gradestringAlways exploratory_tabular: no grain, negatives, contradiction completeness, exact totals or order are guaranteed beyond what the fields below state.
request_idUUID
deployment_idUUID
surface_manifest_hashstringThe query space version the statement ran against.
query_space_schemastringAlways memory_v1.
query_hashstringHash of the normalized statement and the types (never the values) of its parameters. Empty when the statement did not parse.
query_languagestringAlways sql.
saved_queryobject of string, nullableFor a saved query: query_id, namespace, name, version, query_hash.
referenced_viewsarray of stringViews the statement reads.
referenced_functionsarray of stringFunctions it calls.
source_grain_tagsarray of stringThe grain tags of the referenced views.
columnsarray of ResultColumn
rowsarray of arraysOne array per row, values in column order.
returned_row_countinteger ≥ 0
returned_byte_countinteger ≥ 0JSON-encoded size of the returned rows.
limitsResultLimitsThe caps this statement ran under.
truncatedboolean
truncation_reasonstring, nullablerow_cap, byte_cap, or a graph budget (depth_budget, expansion_budget, frontier_budget, result_budget, time_budget).
ordered_resultbooleanThe statement has a top-level ORDER BY.
empty_resultbooleanNo rows were returned (also true on every rejection or failure).
negative_kindnullAlways null: SQL results never carry a typed negative.
execution_started_atdate-time
evaluated_atdate-time, nullableSet only when every referenced view and function answers at one instant (facts_current, graph_edges_current, contradiction_members_current, facts_as_of).
pg_snapshot_atdate-time, nullableThe database snapshot time.
elapsed_msnumber ≥ 0
termination_reasonstringcompleted, rejected or failed.
error_codestring, nullableOne of the SQL query codes.
error_messagestring, nullableSafe to show; never raw database detail.
warningsarray of stringFor example one entry per graph function that hit a budget.
semantic_invocationsarray of SemanticInvocationOne per search function call.
graph_invocationsarray of GraphInvocationOne per graph function call.

ResultColumn

FieldTypeContents
namestring
typestringThe PostgreSQL type name (text, uuid, bigint, timestamp with time zone, …).
nullablebooleanAlways true: PostgreSQL does not report nullability for computed columns.

ResultLimits

FieldType
row_capinteger
byte_capinteger
statement_timeout_msinteger
analytical_tierboolean (always false over HTTP)

SemanticInvocation

What one search function (semantic_*, lexical_*, fetch_chunk_bodies) did.

FieldTypeContents
functionstring
nominatedintegerCandidates the index returned.
confirmedintegerCandidates that held when re-read.
dropped_staleinteger
dropped_filteredinteger, default 0
dropped_ambiguousinteger, default 0
dropped_absentinteger, default 0
dropped_body_mismatchinteger, default 0
dropped_absent_currentinteger, default 0
dropped_absent_projectioninteger, default 0
dropped_hash_mismatchinteger, default 0
policy_generationstring, nullable
embedder_generationstring, nullable
generationstring, nullable
pg_confirmed_atdate-time, nullable
termination_reasonstring, nullablecompleted, 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.

FieldType
ordinalinteger ≥ 0
functiongraph_neighborhood | graph_path | graph_citation_path
truncatedboolean
truncation_reasondepth_budget | expansion_budget | frontier_budget | result_budget | time_budget, nullable
examined_edgesinteger ≥ 0
returned_pathsinteger ≥ 0
effective_depthinteger ≥ 1
effective_expansion_budgetinteger ≥ 1
effective_frontier_budgetinteger ≥ 1
effective_result_budgetinteger ≥ 1
effective_time_budget_msinteger ≥ 1
applied_valid_atdate-time, nullable
applied_believed_atdate-time, nullable
evaluated_atdate-time, nullable

IngestedVersion

Returned by POST /ingest.

FieldTypeContents
deployment_idUUID
doc_idUUIDThe document.
version_idUUIDThe version; pass it to POST /readiness.
content_hashstringSHA-256 of the bytes, hex.
createdbooleantrue for a new version; false when the bytes matched the latest version and nothing new was stored.
mimestring, nullableThe 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.
titlestring, nullableThe document's title, set by its first ingest.
versioning_modesnapshot | living, nullableThe document's versioning mode, set by its first ingest.
version_keystring, nullableThe 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.

FieldType
pipelineboolean
p1boolean
live_graphboolean
p3boolean

PipelineReadinessReport

FieldTypeContents
readybooleanEvery required capability is ready.
versionsarray of VersionPipelineReadinessOne per requested version.
capabilitiesobject: pipeline, p1, live_graph, p3 → CapabilityReadinessAll four, required or not.
document_binding_generationstring, nullableAs in DeploymentBuildInfo.
model_bindingsobject of string to stringAs in DeploymentBuildInfo.
build_revisionstringAs in DeploymentBuildInfo.

VersionPipelineReadiness

FieldTypeContents
version_idUUID
readybooleanEvery stage is succeeded or skipped and finished.
stagesarray of PipelineStageReadinessOne per expected stage.

PipelineStageReadiness

FieldTypeContents
stagestringThe pipeline stage.
component_versionstringThe version of that stage's component the deployment expects.
statusstringmissing, pending, running, succeeded, failed, dead_letter, skipped.
finished_atdate-time, nullable
defer_reasonstring, nullableWhy 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

FieldTypeContents
requiredbooleanYou asked for it.
readyboolean
checked_atdate-time
reasonstringready, or why not (see Ingest).
versionstring, nullablep3: the export digest for one ready requested document; null for multiple documents or incomplete publication.
built_atdate-time, nullableNull for the live corpus, which has no global snapshot build time.
published_atdate-time, nullableNull for the live corpus, which has no global snapshot publication time.

Documents

DocumentPage

FieldTypeContents
documentsarray of DocumentSummary
next_cursorstring, nullablePass to the next request; null on the last page.

DocumentSummary

FieldTypeContents
doc_idUUID
titlestring, nullable
source_kindstringupload for a file sent without a source identity.
source_uristring, nullableThe source_ref, for documents sent with one.
first_seen_atdate-timeNever changes.
latestDocumentVersionSummaryThe newest version that has not been deleted.
servingbooleanSome version of this document is ready and not deleted.
tagsarray of stringsThe names of the document's tags, ordered by name ignoring letter case. Empty when it has none.

DocumentVersionSummary

FieldTypeContents
version_idUUID
version_nointeger
statusstringingesting, converting, structuring, ready, failed, deleted.
ingested_atdate-time
errorstring, nullableWhy 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.

FieldTypeRequiredDefaultConstraints
querystring, nullableno1 to 4,096 characters.
filtersDocumentSearchFiltersno{}
versionscurrent | allnocurrent
timeReadTime, nullablenocurrentWhich editions of a document with declared effective periods are candidates.
kintegerno20Ranked results with query: 1 to 200.
limitintegerno50Browse page size without query: 1 to 200.
cursorstring, nullablenoOnly without query.

DocumentSearchFilters

FieldTypeDefaultContents
familyarray of strings[]Any listed format family.
authorsarray of strings[]Any listed name or address.
recipientsarray of strings[]Any listed name or address.
created_from, created_todate-time with timezone, nullableInclusive range on the declared creation date.
modified_from, modified_todate-time with timezone, nullableInclusive range on the declared modification date.
languagestring, nullable
thread_refstring, nullable
doc_idsarray of UUIDs[]
tagsDocumentTagFilter, nullableThe 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.

FieldTypeDefaultContents
allarray of strings[]The document carries every listed tag.
anyarray of strings[]The document carries at least one listed tag.
nonearray of strings[]The document carries none of the listed tags.

DocumentSearchPage

FieldTypeContents
documentsarray of DocumentSearchResultBest first with a query; newest ingested first without one.
next_cursorstring, nullableThe next page; always null with a query.
truncatedbooleanRanked results exceeded k; false for browse pages.
as_ofdate-timeThe instant this search judges documents at; every page of one search shares it.
people_matchedarray of DocumentPeopleMatchEach distinct person an authors or recipients filter matched; empty without one.
scope_pendingScopePending, nullableExamined documents whose edition in force for time is still being processed.

DocumentSearchResult

FieldTypeContents
doc_idUUID
version_idUUIDThe version the document was judged by.
version_nointeger
statusstringThat version's processing status, as in DocumentVersionSummary.
lineage_titlestring, nullableThe document's title, set by its first ingest.
tagsarray of stringsThe names of the document's tags, ordered by name ignoring letter case.
file_namestring, nullableThe file name this version was ingested under.
titlestring, nullableThe title the caller declared for this version, or the title the file declares when none was.
source_pathstring, nullableWhere the file was at its source when this version was ingested.
p3_pathstring, nullableRelative 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_versionbooleanWhether version_id is the document's served version, independently of P3 publication. Default true.
representation_idUUID, nullableThe described version's converted reading; with version_id it opens exactly that version.
effectivearray of EffectiveIntervalThe described version's in-force intervals, for a document with declared effective periods.
matching_editionsarray of MatchingEditionEvery candidate edition that matched, earliest period first, for a document with declared effective periods.
familystringThe format family.
created_at, modified_atdate-time, nullableDates the document declares.
languagestring, nullable
thread_refstring, nullable
authors, recipientsarray of {name, address}Either field may be null.
extraobjectFormat-specific metadata; not filterable.
overviewstring, nullableA summary of the whole document, when processing produced one. Orientation, not evidence.
other_matching_version_idsarray of UUIDsWith versions: all, the document's other versions that matched.
matched_byarray of name | contentWhich part of the query matched. Empty without a query.
scorenumber, nullableThe combined rank score with a query; null without one.

MatchingEdition

FieldType
version_idUUID
version_nointeger
version_keystring, nullable
representation_idUUID, nullable
effectivearray of EffectiveInterval

DocumentPeopleMatch

FieldTypeContents
roleauthor | recipient
namestring, nullable
addressstring, nullable
documentsintegerMatching documents that list this person.

DocumentDeletion

What DELETE /documents/{doc_id} changed. The counts describe this call only.

FieldTypeContents
doc_idUUIDThe deleted document.
deleted_atdate-timeWhen the document was deleted. For a call that finished a deletion another path started, when the document was first hidden.
claims_retiredintegerClaims that stopped counting as evidence.
relations_closedintegerRelations closed because this document was their only support.
observations_closedintegerObservations closed because this document was their only support.

Tags

Tag

One registered tag, as GET /tags and the other tag routes return it.

FieldTypeContents
tag_idUUIDStable identity; a rename keeps it.
namestringThe current name, with the spelling it was declared with. Unique ignoring letter case.
descriptionstringWhat the tag means and when to apply it.
created_atdate-timeWhen the tag was registered.
updated_atdate-timeWhen its name or description last changed.

TagList

FieldTypeContents
tagsarray of TagOrdered by name, ignoring letter case.

DocumentTags

What POST /documents/{doc_id}/tags left on the document.

FieldTypeContents
doc_idUUID
tagsarray of stringsThe document's tag names after the change, ordered by name ignoring letter case.

Effective periods

EffectivePeriodInput

One period in the body of PUT …/effective-periods ({"periods": [EffectivePeriodInput, …]}, 0 to 1,000 items with distinct starts).

FieldTypeRequiredConstraints
effective_fromdate-timeyesUTC. Included.
effective_untildate-time, nullablenoUTC. Excluded; later than effective_from. null: until the next declared start.

EffectivePeriodsSet

FieldTypeContents
doc_idUUID
version_idUUID
periodsarray of DeclaredEffectivePeriodThe version's periods after the call, by start.
declaredinteger ≥ 0Periods this call added.
retractedinteger ≥ 0Periods this call withdrew.

DeclaredEffectivePeriod

FieldTypeContents
period_idUUID
effective_fromdate-timeAs declared.
effective_untildate-time, nullableAs declared; null means until the next declared start.
declared_atdate-timeWhen the declaration was made.

EffectiveTimeCleared

FieldTypeContents
doc_idUUID
retractedinteger ≥ 0Periods withdrawn.
cleared_atdate-time, nullableWhen the document left effective time; null when it had none.

Sections and references

ReferenceInput

One line of the NDJSON body of PUT …/references.

FieldTypeRequiredDefaultConstraints
kindstringyescites, links_to, attaches, replies_to, refers_to, amends, implements.
from_section_keystring, nullablenoSection key syntax: 1 to 200 characters from A–Z a–z 0–9 _ . : / -.
targetReferenceTargetyes
bindingfloating | pinnednofloatingpinned requires target.version_key.
change_effective_fromdate-time, nullablenoUTC. Only for amends with change_date_known: true, where it is required.
change_date_knownboolean, nullablefor amendsOnly for amends.
source_labelstring, nullableno1 to 200 characters.
contextstring, nullableno1 to 2,000 characters.

ReferenceTarget

FieldTypeRequiredConstraints
source_kindstringyes1 to 128 characters.
source_refstringyes1 to 512 characters.
version_keystring, nullableno1 to 512 characters.
section_keystring, nullablenoSection key syntax.

ReferencesSet

FieldTypeContents
doc_idUUID
version_idUUID
outcomecreated | unchanged | pending_cancelledWhat the call did.
generationReferenceGenerationThe generation the version's intent now names.

ReferenceGenerations

FieldTypeContents
doc_idUUID
version_idUUID
generationsarray of ReferenceGenerationNewest first, at most 100; an active generation is always included.

ReferenceGeneration

FieldTypeContents
generation_idUUID
doc_id, version_idUUID
originsupplied | extracted
statuspending | active | rejected | superseded
request_seqinteger, nullableSupplied sets: the order of the PUT calls for this version.
input_hashstringIdentifies the set's content.
item_countinteger, nullableReferences in the set.
representation_id, crossref_versionnullableExtracted generations only.
errorsarray of {item, field, reason}Why a rejected set was rejected; item is 1-based. At most 100.
created_atdate-time
activated_atdate-time, nullable

SectionHistoryPage

FieldTypeContents
doc_idUUID
section_keystring
periodisedbooleanThe document has declared effective periods; rows are then ordered by period start, otherwise by version_no.
rowsarray of SectionHistoryRow
amendmentsarray of SectionAmendmentFirst page only.
next_cursorstring, nullable
evaluated_at, believed_atdate-timeThe instants the history was read at; a cursor keeps them.

SectionHistoryRow

FieldTypeContents
version_idUUID
version_nointeger
version_keystring, nullable
effectivearray of EffectiveInterval
statuspresent | absent | not_indexed | processing
sectionSectionHistorySection, nullableSet when status is present.

SectionHistorySection

FieldTypeContents
section_idUUID
node_pathstringThe section's place in the version's section tree.
titlestring, nullableThe heading, without its {#key}.
own_content_hashstringHash of the section's own text, subsections excluded.
subtree_content_hashstringHash of the section with its subsections.
changedboolean, nullablesubtree_content_hash differs from the previous row that held the key; null on the first.
own_changedboolean, nullableThe same for own_content_hash.
first_chunk_idsarray of UUIDPassages holding the section's first block.

SectionAmendment

FieldType
crossref_idUUID
from_doc_id, from_version_idUUID
from_section_keystring, nullable
source_labelstring, nullable
bindingfloating | pinned
to_version_keystring, nullable
change_effective_fromdate-time, nullable
change_date_knownboolean

DocumentReferencesRequest

Body of POST /documents/references.

FieldTypeRequiredDefaultConstraints
chunk_idUUID, nullableone of chunk_id, doc_id
doc_idUUID, nullableone of chunk_id, doc_id
section_keystring, nullablenoOnly with doc_id.
directionoutgoing | incoming | bothnoboth
kindsarray of strings, nullableno1 to 7 reference kinds.
timeReadTime, nullablenocurrent; with chunk_id, the chunk's version's in-force time up to now
limitintegerno501 to 200.
cursorstring, nullableno

DocumentReferencesPage

FieldTypeContents
rowsarray of DocumentReference
next_cursorstring, nullableA short page can still carry a cursor.
evaluated_at, believed_atdate-time
too_broadobject, nullable{reason: "too_broad", descendant_keys, limit, explanation} when the section has more than limit (1,000) keyed subsections; rows is then empty.

DocumentReference

FieldTypeContents
directionoutgoing | incoming
crossref_idUUID
kindstringA reference kind.
originsupplied | extracted
bindingfloating | pinned
source_label, contextstring, nullableAs supplied.
change_effective_fromdate-time, nullableamends only.
change_date_knownboolean, nullableamends only.
sourceobjectdoc_id, version_id, version_key, section_key, section_title, window (a ReferenceWindow).
named_targetobjectsource_kind, source_ref, version_key, section_key, exactly as the source names them.
statusstringresolved, target_processing, target_unavailable, target_not_in_force, section_not_in_version, section_not_indexed, pinned_version_unavailable.
targetobject, nullabledoc_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

FieldTypeContents
fromdate-time, nullableIncluded; null is unbounded.
untildate-time, nullableExcluded unless until_inclusive; null is unbounded.
until_inclusivebooleantrue for a closed window, such as an instant. Default false.

ToolDescriptor

One assured operation, as GET /operations returns it.

FieldTypeContents
namestring
descriptionstring
input_schemaobjectJSON Schema of the arguments. Closed (additionalProperties: false).
result_schemaobjectJSON Schema of the result.
result_contractstringenvelope or context_bundle_v2.
output_grainstring, nullablefact, evidence, or null for combined_context.
answer_intentstringidentity, claims_and_sources, facts or combined_context.
mutatesboolean, nullableWhether the operation changes memory. false on all four shipped operations.
versioninteger ≥ 1, nullable
implementation_plan_hashstring of 64 hex characters, nullableIdentifies the exact plan.

DeploymentBuildInfo

FieldTypeContents
build_revisionstringSource revision the image was built from; empty when unknown. Default "".
model_bindingsobject of string to stringModel per pipeline role. Default {}.
document_binding_generationstring, nullable
toolsobject of string to integerMCP 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.

FieldTypeRequiredDefaultConstraints
querystringyes1 to 4,096 characters.
kintegerno101 to 400.
channelsemantic | bm25nosemantic
documentsDocumentSearchFilters, nullablenoOnly results found in matching document versions; returned claims still cite their origin.
timeReadTime, nullablenocurrentOnly text in force for the scope.

ReadTime

The time scope of a text read, chosen by mode.

modeOther fields
currentnone
atat: date-time with a time zone
overlapfrom, to: date-times with a time zone, both included; to not before from
historynone

No other fields are accepted.

AdjacentChunksRequest

Body of POST /chunks/adjacent.

FieldTypeRequiredDefaultConstraints
chunk_idUUIDyes
windowintegerno11 or 2.

The graph, readiness, SQL and saved-query bodies are described with their routes: Graph, Ingest, SQL queries.