# List facts

GET

/v1/memory/facts

```sh
curl --request GET \
  --url 'https://example.com/v1/memory/facts?limit=25&scopeKind=tenant&inherit=true' \
  --header 'Authorization: Bearer <token>'
```

Cursor-paginated: the current revision of each fact the caller may see. That is tenant-wide facts, the projects they may read (with those projects’ orgs), their own user facts, and every end user’s and conversation’s facts in the projects they may write; a tenant admin sees every fact. Filters: `?type=` (exact match on `Fact.type`), `?scope=` (URL-encoded JSON partial memory `Scope`), `?scopeKind + ?scopeId + ?inherit` (discriminated `PlatformScope` triplet — threaded into the binding as `platformScope`; both fields coexist), `?asOf=` (memory as it stood then). Sort order is binding-defined.

## Authorizations

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

## Parameters

### Query Parameters

**limit**

integer

default: 25 >= 1 <= 100

1..100. Default 25.

**cursor**

string

Where the previous page ended: its `nextCursor`, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise `400 bad-input`, and the list starts again without it. Absent → first page.

**type**

string

Filter by fact type (exact match).

**scope**

string

JSON-encoded partial scope object. Every provided key must match. Example: `%7B%22projectId%22%3A%22...%22%7D`.

**scopeKind**

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string

Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

**scopeId**

string

\>= 1 characters

Required IF scopeKind is `org` or `project`. MUST be absent if scopeKind=`tenant` (tenant is implicit from the session). Malformed combinations return 400 scope-invalid.

**inherit**

boolean

default: true

Default `true`. `false` = literal-at-this-scope only (admin/audit view). Load-bearing for policy/config-scoped resources (mcp-endpoints); documented no-op for content-scoped resources (agents/flows/tools/…).

**asOf**

string format: date-time

Read memory as it stood at this time (ISO 8601): the revision that was current then, including one since superseded or deleted.

## Responses

### 200

Page of facts.

application/json

object

**data**

required

Array\<object>

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

**nextCursor**

Opaque cursor for the next page. Absent when `hasMore: false`.

string

**hasMore**

required

boolean

##### Example

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

### 400

Malformed query parameter (e.g. `scope` not valid JSON, `asOf` not a time).

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"
  }
}
```

## See also

- [`POST /v1/memory/facts`: Write a fact](https://docs.kindgi.com/v0.1.10/reference/api/operations/memorywritefact.md)
- [`GET /v1/memory/facts/{factId}`: Fetch a fact](https://docs.kindgi.com/v0.1.10/reference/api/operations/memorygetfact.md)
- [`DELETE /v1/memory/facts/{factId}`: Delete a fact](https://docs.kindgi.com/v0.1.10/reference/api/operations/memorydeletefact.md)
- [`GET /v1/memory/facts/{factId}/revisions`: List a fact's revisions](https://docs.kindgi.com/v0.1.10/reference/api/operations/memorylistfactrevisions.md)
- [Every error code](https://docs.kindgi.com/v0.1.10/reference/errors.md)