Purge one domain's deleted rows past their grace

POST

/v1/retention/sweep/{domain}

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

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

As POST /v1/retention/sweep, for one domain. Requires admin on the tenant.

Authorizations

• bearerAuth

Parameters

Path Parameters

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 *

The domain to sweep (not *).

Request Body

Media typeapplication/json

object

maxPerDomain

The most rows this call purges (default 500); the rest are remaining.

integer

>= 1 <= 10000

Example^generated

{
  "maxPerDomain": 1
}

Responses

200

What was purged.

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

Unknown domain (or *), 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"
  }
}

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