Skip to content
Kindgi

List facts

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

Cursor-paginated. 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). Sort order is binding-defined.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Opaque cursor from a prior response. 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/…).

Responses

Section titled “Responses”

200

Section titled “200”

Page of facts.

Media typeapplication/json
object
data
required
Array<object>
object
id
required

FactId.

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). Additional keys accepted for forward compatibility.

object
tenantId
required
string
userId
string
orgId
string
projectId
string
threadId
string
sessionId
string
key
additional properties
any
version
required

Monotonic version within (scope, id). Supersession increments.

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

FactId of the predecessor when this row supersedes another.

string
nextCursor

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

string
hasMore
required
boolean
Example
{
  "data": [
    {
      "source": {
        "kind": "http-api",
        "refresh": {
          "strategy": "on-read"
        }
      }
    }
  ]
}

400

Section titled “400”

Malformed query parameter (e.g. scope not valid JSON).

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}