---
title: "Create Fact"
method: POST
path: "/v1/facts"
tags: ["v1"]
---

# Create Fact

`POST /v1/facts`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/facts`
- Auth: HTTP bearer

Write a fact directly: a subject, a relation and an object, with no
memory behind it and no extraction.

It is not a write without a model. With a model key configured, the
relation goes through the store's vocabulary (a model may be asked whether
a new relation is one already known, and whether it holds one value at a
time), and a `current` fact goes through the contradiction check: when
open facts of the same subject could conflict with it, a model judges
them and may close one, named in `invalidated`. The fact's words reach
that model's provider and the calls are billed as any other. When one of
those models gives no usable answer nothing is written: 503
`model_unavailable`, retry.

With no model key, no model is asked and no judge closes anything. A
`past` fact closes the open fact it restates either way.

To end a fact yourself, with the date it stopped being true, use
`POST /v1/facts/{fact_id}/forget`, which asks no model.

## Request body

- FactBody
  - `subject` string, required
  - `predicate` string, required
  - `object` string, required
  - `user_id` string, nullable: End user this fact is about. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users/<user_id>/memories and DELETE /v1/agents/<agent_id> address as one URL path segment.
  - `agent_id` string, nullable: Agent namespace. 1 to 255 characters, no '/', no control characters, and not '.' or '..': the id names a namespace that DELETE /v1/users/<user_id>/memories and DELETE /v1/agents/<agent_id> address as one URL path segment.
  - `run_id` string, nullable
  - `subject_type` string
  - `object_is_literal` boolean
  - `confidence` number
  - `valid_from` string, nullable
  - `tense` 'current' | 'past' | 'planned': current | past | planned. A past fact closes the open fact it restates.

## Response `201`

Successful Response

- FactWriteResponse: The write shape of POST /v1/facts (and the facts[] inline on a memory write): the new fact + the ids it superseded.
  - `id` string, required
  - `subject` string, required
  - `predicate` string, required
  - `object` string, required
  - `predicate_family` string, nullable
  - `valid_from` string, nullable
  - `invalidated` string[]
  - `tense` string, nullable
  - `invalid_at` string, nullable
  - `observation_count` integer
  - `user_id` string, nullable
  - `agent_id` string, nullable

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `413`: `payload_too_large`: the body is larger than 2,097,152 bytes, the most this route takes. Refused before it is read; nothing was done.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's writes of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at`, a top-up or a bigger plan). And `agent_cap_exceeded`: a new `agent_id` past the plan's named agents (`limit`, `used`).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: `model_unavailable`: a model the write needs (the one that resolves relations, or the contradiction check) gave no usable answer. Nothing was written; retry. A new fact whose own embedding fails is written anyway, and its vector is computed later by the worker.

---

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