Skip to content
Kindgi

Erase a person's words

POST
/v1/memory/erasures
curl --request POST \
  --url https://example.com/v1/memory/erasures \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "factId": "example" }'

Starts erasing, in the background, one fact (factId), a person (subject: an app’s end user participant, or an external subject facts name) or one conversation (conversationId): their facts, conversations (messages, recall rows), the runs that served them (input, output, journal, snapshots) and the free text they left in provenance; facts written from them go to review. Answers 202 with the erasure; follow it with GET /v1/memory/erasures/{erasureId}. A completed erasure keeps no identifier, only a keyed hash for a replay after a backup restore; warnings says when this deployment can’t keep one (erasure-unmatchable: no erasure ledger key, KINDGI_ERASURE_LEDGER_KEY). Requires admin on the tenant.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

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 Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:

One fact.

object
factId
required
string
>= 1 characters <= 256 characters

Responses

Section titled “Responses”

202

Section titled “202”

Started.

Media typeapplication/json
object
id
required
string format: uuid
selectorKind
required
string
Allowed values: fact participant external conversation
selector
One of:

One fact.

object
factId
required
string
>= 1 characters <= 256 characters
status
required

waiting-on-run: a turn of the person’s sits in a flow that serves other people; the erasure waits for it (waitingOn) until its deadline, then cancels it.

string
Allowed values: pending running waiting-on-run completed failed
phase
required

Where a running erasure is: seed, expand, settle (the person’s unfinished runs end, or it waits for them, before anything is cleared), erase, then done.

string
Allowed values: seed expand settle erase done
requestedBy
required

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

string
matchable
required

A replay after a backup restore can find this person again: a keyed hash was kept.

boolean
counts
required

What each store cleared or deleted, by store.

object
key
additional properties
integer
attempts
required

Failed attempts so far.

integer
lastError

The last failure’s code, or not-yet:<reason> while it waits. Never content.

string
waitingOn

The run it waits (or waited) for, and until when; kept as the record of the wait.

object
runId
required
string format: uuid
until
string format: date-time
forced

A tenant admin said not to wait.

boolean
settleRoundsCapped

Runs of the person’s kept appearing, round after round: the erasure went on to erase after its last round rather than wait any longer. Absent: it didn’t.

boolean
createdAt
required
string format: date-time
startedAt
string format: date-time
completedAt
string format: date-time
replayedAt
string format: date-time
warnings
Array<object>
object
code
required

erasure-unmatchable: this deployment has no erasure ledger key (KINDGI_ERASURE_LEDGER_KEY), so a replay after a restore can’t find this person.

string
Allowed values: erasure-unmatchable
message
required
string
Example
{
  "selectorKind": "fact",
  "selector": {
    "subject": {
      "kind": "participant"
    }
  },
  "status": "pending",
  "phase": "seed",
  "forced": true,
  "settleRoundsCapped": true,
  "warnings": [
    {
      "code": "erasure-unmatchable"
    }
  ]
}

400

Section titled “400”

Not exactly one of factId, subject or conversationId; or a subject of kind user (erasing a Kindgi user isn’t offered).

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”

Not a tenant admin.

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”

legal-hold: a fact it reaches is under legal hold (details.factIds); nothing started.

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