Skip to content
Kindgi

Mark a fact verified

POST
/v1/memory/facts/{factId}/verify
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

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
factId
required
string

The fact id (kept across revisions).

Header Parameters

Section titled “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

Section titled “Request Body”
Media typeapplication/json
object
expectVersion
integer
>= 1
Examplegenerated
{
  "expectVersion": 1
}

Responses

Section titled “Responses”

200

Section titled “200”

The verified revision.

Media typeapplication/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
{
  "source": {
    "kind": "http-api",
    "refresh": {
      "strategy": "on-read"
    }
  },
  "trust": "verified",
  "attributedTo": {
    "kind": "user"
  },
  "subjects": [
    {
      "kind": "participant"
    }
  ],
  "invalidationReason": "superseded",
  "review": "pending"
}

400

Section titled “400”

Malformed request body.

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

403

Section titled “403”

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

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

404

Section titled “404”

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

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

409

Section titled “409”

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

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

500

Section titled “500”

Server error (unmapped domain code or framework crash).

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

501

Section titled “501”

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

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