Skip to content
Kindgi

Purge the deleted rows past their grace

POST
/v1/retention/sweep
curl --request POST \
  --url https://example.com/v1/retention/sweep \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "domain": "org", "maxPerDomain": 1 }'

Purges, for good, every tombstoned row past the grace of the retention policy that covers its domain (or only domain’s), up to maxPerDomain per domain; remaining counts what is left for the next call. Nothing sweeps on its own: call this (or POST /v1/retention/sweep/{domain}) from a schedule. A hold (graceSeconds: -1) keeps its domain’s rows. Idempotent: a second call purges nothing new. Requires admin on the tenant.

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
domain

Sweep only this domain. Absent: every domain.

string
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *
maxPerDomain

The most rows one call purges per domain (default 500); the rest are remaining.

integer
>= 1 <= 10000

Responses

Section titled “Responses”

200

Section titled “200”

What was purged, per domain.

Media typeapplication/json
object
perDomain
required
Array<object>
object
domain
required

The kind of record a retention policy covers. * covers every domain without a policy of its own, except memory and conversation: they hold people’s words, so only a policy naming them purges them.

string
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *
purged
required
integer
remaining
required

Rows past grace this call left (the maxPerDomain cap); sweep again.

integer
policyId

The retention policy that applied.

string
missingAdapter

Present when this deployment can’t purge the domain (no adapter).

boolean
totalPurged
required
integer
conflicts

Domains more than one retention policy covers. Absent or empty: none.

Array<object>
object
domain
required

The kind of record a retention policy covers. * covers every domain without a policy of its own, except memory and conversation: they hold people’s words, so only a policy naming them purges them.

string
Allowed values: org agent flow tool eval_suite guardrail mcp_endpoint env secret run artifact policy judgment judge_class provider memory conversation api_key service_account *
policyIds
required

Every policy id that covers the domain, sorted.

Array<string>
>= 2 items
appliedPolicyId
required

The one that applies: the policy whose latest version is highest, and on equal versions the lower policy id. Unregister the others.

string
Example
{
  "perDomain": [
    {
      "domain": "org",
      "missingAdapter": true
    }
  ],
  "conflicts": [
    {
      "domain": "org"
    }
  ]
}

400

Section titled “400”

Unknown domain, or maxPerDomain outside 1..10000.

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”

Idempotency-Key was reused with a different body, or resource-state conflict.

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