# Mark a fact verified

POST

/v1/memory/facts/{factId}/verify

```sh
curl --request POST \
  --url https://example.com/v1/memory/facts/example/verify \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "expectVersion": 1 }'
```

A person who may write in its scope checked it: the next revision has `trust: verified`, `verifiedBy` and `verifiedAt`, and the same content.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.1.9/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**factId**

required

string

The fact id (kept across revisions).

### Header Parameters

**Idempotency-Key**

string

\>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per `docs/API-ROUTE-CONVENTIONS.md` §3.1). A retry sent while the first request still runs is answered `409 idempotency-key-in-flight` with `Retry-After`, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets `409 idempotency-key-replay-withheld`, with the first request’s status and when it succeeded (from 0.1.5).

## Request Body

application/json

object

**expectVersion**

integer

\>= 1

##### Examplegenerated

```json
{
  "expectVersion": 1
}
```

## Responses

### 200

The verified revision.

application/json

object

**id**

required

The fact id, kept across revisions (for a fact never superseded, also its one revision id).

string

**revisionId**

This revision’s own id; absent where it equals `id`.

string

**type**

required

Fact type identifier (pack-defined; a few are framework-standard).

string

**scope**

required

Fact scope object. `tenantId` is required; every optional key narrows the fact (`userId`, `orgId`, `projectId`, `threadId`, `sessionId`, `participantId`). A fact is readable by whoever has every container it names. Additional keys accepted for forward compatibility.

object

**tenantId**

required

string

**userId**

string

**orgId**

string

**projectId**

string

**threadId**

string

**sessionId**

string

**participantId**

An app’s end user, by the app’s own id: a fact private to that participant’s runs. Needs `projectId`.

string

\>= 1 characters

**_key_**

additional properties

any

**version**

required

The revision number within the fact: 1, then one more per supersede or verify.

integer

\>= 1

**createdAt**

required

string format: date-time

**updatedAt**

string format: date-time

**content**

Free-form structured payload.

**contentRef**

`blob://<provider>/<bucket>/<key>` when the payload is stored externally.

string

**contentHash**

string

**size**

integer

**embeddingModel**

string

**retention**

object

**keepUntil**

string format: date-time

**keepDays**

integer

\>= 1

**legalHold**

boolean

**source**

object

**kind**

required

string

Allowed values: http-api blob mcp-tool external-db user-input

**uri**

string

**freshness**

required

object

**ttlSeconds**

integer

**lastVerifiedAt**

string format: date-time

**etag**

string

**sourceVersion**

string

**refresh**

required

object

**strategy**

required

string

Allowed values: on-read background manual

**handler**

string

**priority**

integer

**causedByLogId**

Array\<string>

**supersedes**

The revision this one replaced.

string

**trust**

`verified`: a person with the right checked it. `asserted`: an app or a person wrote it. `unverified`: an agent remembered it during a conversation. Absent on facts from before trust was recorded: `asserted`.

string

Allowed values: verified asserted unverified

**verifiedBy**

string

**verifiedAt**

string format: date-time

**attributedTo**

Who asserted a fact, set by the server from the writer.

object

**kind**

required

string

Allowed values: user service agent

**id**

required

string

**agentVersion**

string

**generatedBy**

The run step that wrote a fact, for one an agent wrote.

object

**runId**

required

string

**stepId**

string

**toolCallId**

string

**subjects**

Array\<object>

Whom a fact is about: what access and erasure requests by person find.

object

**kind**

required

string

Allowed values: participant user external

**id**

required

string

\>= 1 characters

**validFrom**

When the fact starts being true in the world; absent: always.

string format: date-time

**validUntil**

When the fact stops being true in the world; absent: still true.

string format: date-time

**observedAt**

When it was said or seen.

string format: date-time

**invalidatedAt**

When this revision stopped being current; absent: it is current.

string format: date-time

**invalidatedBy**

`user:<id>` or `service:<id>`.

string

**invalidationReason**

string

Allowed values: superseded deleted erased expired

**review**

`pending` while a person must approve it: a pending fact is never retrieved.

string

Allowed values: pending

**expiresAt**

When this revision stops being readable: from its retention (`keepUntil`, or `keepDays` from the fact’s first write), or an agent-remembered fact’s unverified window. No read returns it after; absent: it doesn’t expire.

string format: date-time

##### Example

```json
{
  "source": {
    "kind": "http-api",
    "refresh": {
      "strategy": "on-read"
    }
  },
  "trust": "verified",
  "attributedTo": {
    "kind": "user"
  },
  "subjects": [
    {
      "kind": "participant"
    }
  ],
  "invalidationReason": "superseded",
  "review": "pending"
}
```

### 400

Malformed request body.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 401

Missing / malformed / expired / revoked bearer token.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 403

`permission-denied`: the caller may not write in the fact’s scope.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

No fact with that id the caller may see, or it was deleted.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 409

`fact-changed`: the current revision is not `expectVersion`; `legal-hold`: the fact is under legal hold.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 413

The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 500

Server error (unmapped domain code or framework crash).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 501

`memory-operation-unsupported`: this runtime’s memory can’t verify facts.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`GET /v1/memory/facts`: List facts](https://docs.kindgi.com/v0.1.9/reference/api/operations/memorylistfacts.md)
- [`POST /v1/memory/facts`: Write a fact](https://docs.kindgi.com/v0.1.9/reference/api/operations/memorywritefact.md)
- [`GET /v1/memory/facts/{factId}`: Fetch a fact](https://docs.kindgi.com/v0.1.9/reference/api/operations/memorygetfact.md)
- [`DELETE /v1/memory/facts/{factId}`: Delete a fact](https://docs.kindgi.com/v0.1.9/reference/api/operations/memorydeletefact.md)
- [Error code `fact-changed`](https://docs.kindgi.com/v0.1.9/reference/errors.md#fact-changed)
- [Error code `legal-hold`](https://docs.kindgi.com/v0.1.9/reference/errors.md#legal-hold)
- [Error code `memory-operation-unsupported`](https://docs.kindgi.com/v0.1.9/reference/errors.md#memory-operation-unsupported)
- [Error code `permission-denied`](https://docs.kindgi.com/v0.1.9/reference/errors.md#permission-denied)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.1.9/reference/errors.md#request-too-large)
- [Every error code](https://docs.kindgi.com/v0.1.9/reference/errors.md)