---
title: "Record a claim about a subject"
method: POST
path: "/coord/v1/assert"
tags: ["Canon"]
---

# Record a claim about a subject

`POST /coord/v1/assert`

## Request

- Base URL: `https://api.infolang.ai`
- URL: `https://api.infolang.ai/coord/v1/assert`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Appends an assertion. Existing assertions are never edited or deleted — a retraction is a new assertion with `retract: true`, and `supersedes` must name a SAME-SUBJECT assertion id (supersession is by exact subject identity, never by similarity).

`governing_resource` and `fence` travel together (both or neither): the write lands only while that fence is the one currently held for the resource, so **a stale fence records nothing and answers 403**.

Requested `authority` is clamped server-side to the credential's ceiling; the response reports the authority actually recorded.

Requires the `coord:write` scope on the presented credential. Enforced by Kairos on this surface — the gateway forwards the credential without inspecting it. A credential with no scope record resolves to `LEGACY_DEFAULT`, which does NOT include `coord:write`: mint a key with it explicitly (`POST /v2/workspaces/{id}/keys`) or grant it through OAuth consent.

**Canon** — the coordination layer. Where memory answers *what do my agents know*, Canon answers *what do my agents agree is true*: an append-only assertion store with enforced authority ordering (`operator` > `observation` > `inference` — **authority outranks recency**), bitemporal reads (valid time vs transaction time), explicit contested state, and advisory claims with fencing tokens.

Proxied verbatim to Kairos; the gateway authenticates and parses NOTHING here, so the `Authorization` header goes upstream untouched and Kairos is the sole authority — the same terms as `/v1`. Either `il_*` credential is accepted; a Supabase session JWT is not.

**Canon is optional per deployment, and detectable.** Where it is not enabled, EVERY `/coord/v1` path answers `404` — including the four verbs below — and the gateway forwards that 404 unchanged rather than substituting an error of its own. **The memory API is completely unaffected either way**: enabling or disabling Canon changes nothing about `/v1`, `/v2` or `/mcp`. Probe `GET /coord/v1/healthz` (or read `capabilities.canon` from `GET /v2/me`) before relying on Canon.

## Request body

- object
  - `subject` string, required: Exact identity of the thing being asserted about. Never resolved by similarity — supersession requires naming the same subject exactly
  - `claim` unknown
  - `mode` 'correct' | 'update' | 'refine' | 'escalate', required
  - `authority` 'inference' | 'observation' | 'operator', required: REQUESTED authority. Clamped server-side to the calling credential's ceiling; the response reports what was actually recorded, which may be lower
  - `retract` boolean: A retraction is a NEW assertion, not a delete — the store is append-only and nothing is ever edited away
  - `valid_time` string, date-time
  - `evidence` string[]
  - `supersedes` string: Id of a SAME-SUBJECT assertion this one supersedes
  - `governing_resource` string: Resource whose held claim protects this write. Must be sent together with `fence` — both or neither
  - `fence` integer: Fencing token from `claim`. Required iff `governing_resource` is set

## Response `200`

Recorded. `authority` is what was STORED, not necessarily what was requested

- object
  - `id` string, required
  - `authority` 'inference' | 'observation' | 'operator', required: Authority actually RECORDED — may be lower than requested
  - `similar_existing_subjects` string[]: Write-time drift advisory: close existing subjects. A pointer only — nothing was merged, and nothing will be
  - `mirrored` boolean
  - `broadcast` boolean

## Other responses

- `400`: Malformed body — `governing_resource` without `fence` (or the reverse), unknown `mode`, missing `subject`/`claim`
- `401`: Missing or invalid credential (Kairos's verdict)
- `403`: Stale fence — the governing resource's held fence no longer matches. NOTHING was recorded
- `404`: Canon is not enabled for this deployment. Every `/coord/v1` path answers 404; the memory API is unaffected

---

[API](https://skmtc.dev/infolang/apis/infolang-api.md) · [All operations](https://skmtc.dev/infolang/apis/infolang-api/llms.txt) · [OpenAPI document](https://skmtc.dev/infolang/apis/infolang-api/revisions/d04bf6de72c8?raw)