Skip to main content
The moderation workflow lets you open, track, and close formal review cases against providers or agents. When you create a case, you can optionally trigger an immediate block or provider revocation so the subject is taken offline while the review is in progress.

​
Create a moderation case

POST /v1/admin/moderation/cases
Opens a new moderation case and returns the created ModerationCase. If auto_block is true, the target is blocked immediately. If auto_revoke_provider is true, the target provider is revoked immediately.

​
Request Body

​
target_kind
string
required
The type of entity under review. Either "provider" or "agent".
​
target_id
string
required
The identifier of the provider or agent under review.
​
created_by
string
required
Identifier of the moderator or system opening this case.
​
reason
string
required
Description of why this case is being opened.
​
auto_block
boolean
If true, the target entity is blocked at case creation time. Defaults to false.
​
auto_revoke_provider
boolean
If true and target_kind is "provider", the provider is revoked at case creation time. Defaults to false.

​
Example

curl -X POST http://your-node:8042/v1/admin/moderation/cases \
  -H 'content-type: application/json' \
  -d '{
    "target_kind": "agent",
    "target_id": "stripe-agent",
    "created_by": "moderator-a",
    "reason": "policy violation",
    "auto_block": true,
    "auto_revoke_provider": false
  }'

​
List moderation cases

GET /v1/admin/moderation/cases
Returns all moderation cases, optionally filtered by target entity or case status.

​
Query Parameters

​
target_kind
string
Filter by target type. Either "provider" or "agent".
​
target_id
string
Filter by the identifier of the provider or agent under review.
​
status
string
Filter by case status. One of open, actioned, resolved, or rejected.

​
Example

curl 'http://your-node:8042/v1/admin/moderation/cases?target_kind=agent&status=open'

​
Resolve a moderation case

POST /v1/admin/moderation/cases/:case_id/resolve
Closes a moderation case and records the outcome. Optionally clears a block on the target or marks the case as rejected.

​
Path Parameters

​
case_id
string (UUID)
required
The UUID of the moderation case to resolve.

​
Request Body

​
resolved_by
string
required
Identifier of the moderator resolving this case.
​
resolution_notes
string
required
Mandatory notes describing the resolution outcome.
​
clear_block
boolean
If true, any active block on the target entity is lifted. Defaults to false.
​
reject_case
boolean
If true, the case status is set to rejected rather than resolved. Defaults to false.

​
Example

curl -X POST http://your-node:8042/v1/admin/moderation/cases/018f7b4c-1234-7000-bbbb-111111111111/resolve \
  -H 'content-type: application/json' \
  -d '{
    "resolved_by": "moderator-a",
    "resolution_notes": "Reviewed and cleared. No policy breach confirmed.",
    "clear_block": true,
    "reject_case": false
  }'

​
Response

All three endpoints return a ModerationCase.
​
case_id
string (UUID)
required
Unique identifier for this moderation case.
​
target_kind
string
required
Type of the entity under review. Either "provider" or "agent".
​
target_id
string
required
Identifier of the provider or agent under review.
​
created_by
string
required
Moderator or system that opened this case.
​
reason
string
required
Description of why the case was opened.
​
status
string
required
Current case status. One of open, actioned, resolved, or rejected.
​
action_taken
string
required
Action recorded against the target. One of none, provider_blocked, provider_unblocked, provider_revoked, agent_blocked, or agent_unblocked.
​
resolution_notes
string
Notes from the moderator who resolved the case. Present after resolution.
​
resolved_by
string
Identifier of the moderator who resolved the case. Present after resolution.
​
created_at
string (ISO 8601)
required
UTC timestamp when this case was opened.
​
updated_at
string (ISO 8601)
required
UTC timestamp of the most recent update to this case.

​
Example response

{
  "case_id": "018f7b4c-1234-7000-bbbb-111111111111",
  "target_kind": "agent",
  "target_id": "stripe-agent",
  "created_by": "moderator-a",
  "reason": "policy violation",
  "status": "resolved",
  "action_taken": "agent_blocked",
  "resolution_notes": "Reviewed and cleared. No policy breach confirmed.",
  "resolved_by": "moderator-a",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-01-15T13:00:00Z"
}