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

• Same-origin — path relative to the deployment root.

Purges, for good, every tombstoned row past its grace (or only domain’s): the grace of the retention policy that covers its domain, or this server’s limit for the domain when no policy covers it or the policy keeps rows longer (limitApplied), 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, unless the domain has a limit. Idempotent: a second call purges nothing new. Requires admin on the tenant.

Authorizations

• bearerAuth

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

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

limitApplied

Present when this server’s retention limit set the grace (see RetentionScheduledItem.limitApplied).

boolean

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",
      "limitApplied": true,
      "missingAdapter": true
    }
  ],
  "conflicts": [
    {
      "domain": "org"
    }
  ]
}

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

Example^generated

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

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

Example^generated

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

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

Example^generated

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

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

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).

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

Example^generated

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

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

Example^generated

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

See also

• POST /v1/retention/sweep/{domain}: Purge one domain's deleted rows past their grace
• Keep and purge deleted data
• Error code request-too-large
• Every error code