Endpoints
Assertions are source claims with evidence spans and resolved identity links.
Resolution status describes processing of the claim;
resolved does not prove
that the claim is true. See assertion concepts for the
lifecycle and the distinction from truth maintenance.
Search Assertions
POST /v1/assertions/search
Search assertions using text or resolved entity links, with optional status,
source, and predicate filters. Prefer identity filters when you already know
the entity; text search also helps find unresolved mentions.
Search requires read:assertion; a missing scope returns 403 even when no
records match. Results, counts, and pagination are computed after record
authorization, including searches filtered by entity links.
total counts authorized matches in the current scan. Without a text query,
it counts matches remaining after the supplied cursor; with a text query,
it counts all authorized matches before the page offset is applied. Continue
with the returned cursor unchanged and the same filters while has_more is
true.
string
Text query over subject, predicate, object text, and object literal.
string
Resolved entity ID appearing as either subject or object.
string
Resolved subject entity ID.
string
Resolved object entity ID.
string
Filter by resolution status. One of:
pending, resolved, partial, abstained, failed, superseded.string
Filter by source record ID.
string
Filter by predicate string (e.g.,
works_at).boolean
default:"false"
Include soft-deleted assertions.
integer
default:"50"
Maximum results to return.
string
Pagination cursor from a previous response.
Create Assertion
POST /v1/assertions accepts a complete Assertion record and returns 201
with the stored record. It does not generate evidence or queue extraction from
a three-field claim. Prefer document ingestion when adding
new source material.
The JSON body must include the common record fields
(id, space_id, created_at, updated_at, created_by, provenance, and
security) plus these assertion fields:
evidence requires revision (a document revision record ID), start, end,
and quote_hash; node is optional. Supply verified offsets and a hash of the
actual source quote. Do not invent provenance to satisfy this schema.
Optional fields include predicate_id, source_event_time, resolution_status
(default pending), subject_entity, object_entity, confidence, and resolution
metadata. Returned search/get examples below are abbreviated; full records
include all required fields.
Get Assertion
GET /v1/assertions/{id}
Retrieve a single assertion by its ID.
string
required
Assertion record ID (e.g.,
assertion:550e8400-...).Delete and restore
DELETE /v1/assertions/{id} requires write:assertion and record write
authorization. It sets deleted_at and returns 204 without a record body.
Ordinary reads then return 404; search excludes the record unless the caller
requests include_deleted and is authorized to read it. Deleting an already
deleted or missing assertion returns 404.
POST /v1/assertions/{id}/restore clears the soft-deletion marker and returns
the assertion as JSON. It requires both write:assertion and read:assertion
with their record checks before changing the row. A write-only caller receives
403, including when the requested row is already active. A missing row in the
caller’s space returns 404. Restoration retains the existing security
classification and evidence; it does not create a new extraction or adjudicate
the claim.
Delete, restore, and resolution updates can return 409 if authorization
fields or the soft-deletion marker change before the write. See
authorization conflicts.
Update Resolution Status
PATCH /v1/assertions/{id}/resolution
Update the resolution status of an existing assertion. Because the response
contains the existing assertion’s content, this route requires both
write:assertion and read:assertion with their record checks before changing
the status. A write-only caller receives 403 without a status change.
Changing this field alone does not resolve entity references, generate evidence,
or perform truth adjudication.
The update writes the resolution status and supplied rationale without replacing
security, subjects, entity links, or evidence. Omitting rationale keeps the
stored retry_state.abstention_reason unchanged.
string
required
Assertion record ID.
string
required
New resolution status. One of:
pending, resolved, partial, abstained, failed, superseded.string
Optional rationale for the status change.