Change a fact's content

POST

/v1/memory/facts/{factId}/supersede

const url = 'https://example.com/v1/memory/facts/example/supersede';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"content":"example","expectVersion":1,"retention":{"keepUntil":"2026-04-15T12:00:00Z","keepDays":1,"legalHold":true},"subjects":[{"kind":"participant","id":"example"}],"validFrom":"2026-04-15T12:00:00Z","validUntil":"2026-04-15T12:00:00Z","observedAt":"2026-04-15T12:00:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/memory/facts/example/supersede \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content": "example", "expectVersion": 1, "retention": { "keepUntil": "2026-04-15T12:00:00Z", "keepDays": 1, "legalHold": true }, "subjects": [ { "kind": "participant", "id": "example" } ], "validFrom": "2026-04-15T12:00:00Z", "validUntil": "2026-04-15T12:00:00Z", "observedAt": "2026-04-15T12:00:00Z" }'

Writes the next revision (same fact id, version one more) and closes the current one; the old revision stays readable with ?version=, ?asOf= and in the history until the retention sweep removes it. expectVersion refuses if someone changed it first.

Authorizations

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^required

application/json

The fact’s next revision: new content, and optionally new retention, subjects and times (absent ones keep their current values). Its scope and type stay. expectVersion: only if the current revision is still this one.

object

content

required

Free-form structured payload.

expectVersion

integer

>= 1

retention

object

keepUntil

string format: date-time

keepDays

integer

>= 1

legalHold

boolean

subjects

Array<object>

<= 20 items

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

object

kind

required

string

Allowed values: participant user external

required

string

>= 1 characters

validFrom

string format: date-time

validUntil

string format: date-time

observedAt

string format: date-time

Responses

200

The new revision.

application/json

object

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

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

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

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

Example^generated

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

Example^generated

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

Example^generated

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

Example^generated

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

409

fact-changed: the current revision is not expectVersion (details.currentVersion); 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

Example^generated

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

Example^generated

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

Example^generated

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

Change a fact's content

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated