---
title: "Record a declared structured fact"
method: POST
path: "/v1/ingest/fact"
tags: ["Ingest"]
---

# Record a declared structured fact

`POST /v1/ingest/fact`

## Request

- Base URL: `https://brain.inite.ai`
- URL: `https://brain.inite.ai/v1/ingest/fact`
- Auth: HTTP bearer

The headline write. Resolves the entity, embeds the claim and runs bitemporal conflict resolution against the standing timeline: the response `outcome` says what the resolver decided (INSERTED / INSERTED_HISTORICAL / CORROBORATED / SUPERSEDED / COMPETING / REJECTED), never just "ok". `userId` stamps a per-user memory scope (migration 0055) — scope-local conflict resolution, invisible to every other user of the tenant and to requests that don't assert one. `explain: true` adds the deterministic conflict narrative on a SUPERSEDED / COMPETING outcome. Source: src/ingest/ingest.controller.ts.

Required scope: `brain:write`.

## Request body

- IngestFactRequest
  - `confidence` number
  - `entityRef` EntityRef, required
    - `entityId` string
    - `id` string
    - `vertical` string
  - `expectedUntil` string
  - `explain` boolean
  - `metadata` object
  - `object` string, required
  - `predicate` string, required
  - `source` FactSource, required
    - `conversationId` string
    - `episodeIds` string[]
    - `eventId` string
    - `evidence` SourceEvidence[]
      - `kind` 'event' | 'message' | 'conversation' | 'url' | 'document' | 'commit' | 'other', required
      - `note` string
      - `ref` string, required
    - `messageId` string
    - `recorder` string
    - `vertical` string, required
  - `userId` string
  - `validFrom` string, required
  - `validUntil` string

## Response `201`

The resolver's decision.

- IngestFactResponse
  - `competingFactIds` string[]
  - `conflictExplanation` ConflictExplanation
  - `corroboratedFactId` string
  - `factId` string, nullable, required
  - `outcome` 'INSERTED' | 'INSERTED_HISTORICAL' | 'CORROBORATED' | 'SUPERSEDED' | 'COMPETING' | 'REJECTED', required
  - `reason` string
  - `supersededByFactId` string
  - `supersededFactIds` string[]

## Other responses

- `400`: Validation failed.
- `401`: Missing or unknown bearer key.
- `403`: The key lacks the required scope.

---

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