---
title: "Read what is currently believed about one or more subjects"
method: POST
path: "/coord/v1/beliefs"
tags: ["Canon"]
---

# Read what is currently believed about one or more subjects

`POST /coord/v1/beliefs`

## Request

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

Resolves each subject through authority ordering and returns the `winner` alongside any `peers`. **A non-empty `peers` array means the subject is contested and the winner alone is not the answer** — render the disagreement rather than hiding it.

`as_of` asks valid time (*what was true then*); `known_at` asks transaction time (*what did we believe then*) — the audit question, which recovers a past belief even after it was superseded.

Requires the `coord:read` 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:read`: 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
  - `subjects` string[]
  - `as_of` string, date-time: VALID-time cutoff — what was true as of this instant
  - `known_at` string, date-time: TRANSACTION-time cutoff — what was BELIEVED as of this instant. The audit question: a past instant recovers what was believed then, even if it has since been superseded
  - `include_superseded` boolean

## Response `200`

Per-subject belief resolution

- object
  - `beliefs` object[], required
    - `subject` string, required
    - `winner` object, required
      - `id` string, required
      - `subject` string, required
      - `claim` unknown
      - `mode` 'correct' | 'update' | 'refine' | 'escalate', required
      - `authority` 'inference' | 'observation' | 'operator', required
      - `valid_time` string, date-time
      - `tx_time` string, date-time
      - `retracted` boolean
    - `peers` object[], required: NON-EMPTY MEANS CONTESTED — the winner alone is not the answer
      - `id` string, required
      - `subject` string, required
      - `claim` unknown
      - `mode` 'correct' | 'update' | 'refine' | 'escalate', required
      - `authority` 'inference' | 'observation' | 'operator', required
      - `valid_time` string, date-time
      - `tx_time` string, date-time
      - `retracted` boolean
    - `contested` boolean, required
    - `near_misses` string[]: Lexical pointers surfaced on a miss
    - `discovery` string[]: Semantic candidates, only where the memory lane is configured. Proposals re-verified against the fold, never raw search results

## Other responses

- `400`: Neither `subject` nor `subjects` given, or both
- `401`: Missing or invalid credential (Kairos's verdict)
- `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)