v4

latestOpenAPI 3.1.02026-08-08349225311.7 KB
runtime_mutations
ckg

Create Human Evidence Endpoint

Record a reader-selected span as file-captured evidence.

A user action, so it authenticates like the other reader-facing routes rather than with require_kernel_caller — and unlike /api/evidence it cannot create notebook-captured variable evidence, whose value must still come from a kernel read.

The claim's content is the verified quote; a reader's note becomes the title, so an agent reading this back never sees an unverified sentence presented as a quotation from the file.

There is a window between the verifying read and the insert in which the file can change. It is deliberately not locked: the quote is re-verified on every read, so a span invalidated in that window simply shows as diverged the first time the claim is displayed.

post/api/projects/{project_id}/human-evidence

Path parameters

project_idstring required

Request body

notestring nullable

Optional reader caption; becomes the claim's title.

recall_priority'global' | 'high' | 'medium' | 'low'

How readily a claim should enter an agent's context.

This is a query-independent prior authored by the agent that files the claim. It is not relevance, confidence, or truth: a Low claim that is highly relevant to the current work must still be able to outrank an irrelevant Global one once the recall system ranks candidates.

GLOBAL is the only value with delivery semantics rather than ranking semantics: it is injected unconditionally into every agent in the workspace. Every claim type carries a priority — evidence, figures, and findings can all be the thing future agents most need to see.

Response

Successful Response

claim_idstring required