> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Moderation Cases for Providers and Agents — Admin API

> Create, list, and resolve moderation cases for providers and agents. Cases can automatically block or revoke the subject on creation.

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

<ParamField body="target_kind" type="string" required>
  The type of entity under review. Either `"provider"` or `"agent"`.
</ParamField>

<ParamField body="target_id" type="string" required>
  The identifier of the provider or agent under review.
</ParamField>

<ParamField body="created_by" type="string" required>
  Identifier of the moderator or system opening this case.
</ParamField>

<ParamField body="reason" type="string" required>
  Description of why this case is being opened.
</ParamField>

<ParamField body="auto_block" type="boolean">
  If `true`, the target entity is blocked at case creation time. Defaults to `false`.
</ParamField>

<ParamField body="auto_revoke_provider" type="boolean">
  If `true` and `target_kind` is `"provider"`, the provider is revoked at case creation time. Defaults to `false`.
</ParamField>

### Example

```bash theme={null}
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

<ParamField query="target_kind" type="string">
  Filter by target type. Either `"provider"` or `"agent"`.
</ParamField>

<ParamField query="target_id" type="string">
  Filter by the identifier of the provider or agent under review.
</ParamField>

<ParamField query="status" type="string">
  Filter by case status. One of `open`, `actioned`, `resolved`, or `rejected`.
</ParamField>

### Example

```bash theme={null}
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

<ParamField path="case_id" type="string (UUID)" required>
  The UUID of the moderation case to resolve.
</ParamField>

### Request Body

<ParamField body="resolved_by" type="string" required>
  Identifier of the moderator resolving this case.
</ParamField>

<ParamField body="resolution_notes" type="string" required>
  Mandatory notes describing the resolution outcome.
</ParamField>

<ParamField body="clear_block" type="boolean">
  If `true`, any active block on the target entity is lifted. Defaults to `false`.
</ParamField>

<ParamField body="reject_case" type="boolean">
  If `true`, the case status is set to `rejected` rather than `resolved`. Defaults to `false`.
</ParamField>

### Example

```bash theme={null}
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`.

<ResponseField name="case_id" type="string (UUID)" required>
  Unique identifier for this moderation case.
</ResponseField>

<ResponseField name="target_kind" type="string" required>
  Type of the entity under review. Either `"provider"` or `"agent"`.
</ResponseField>

<ResponseField name="target_id" type="string" required>
  Identifier of the provider or agent under review.
</ResponseField>

<ResponseField name="created_by" type="string" required>
  Moderator or system that opened this case.
</ResponseField>

<ResponseField name="reason" type="string" required>
  Description of why the case was opened.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current case status. One of `open`, `actioned`, `resolved`, or `rejected`.
</ResponseField>

<ResponseField name="action_taken" type="string" required>
  Action recorded against the target. One of `none`, `provider_blocked`, `provider_unblocked`, `provider_revoked`, `agent_blocked`, or `agent_unblocked`.
</ResponseField>

<ResponseField name="resolution_notes" type="string">
  Notes from the moderator who resolved the case. Present after resolution.
</ResponseField>

<ResponseField name="resolved_by" type="string">
  Identifier of the moderator who resolved the case. Present after resolution.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)" required>
  UTC timestamp when this case was opened.
</ResponseField>

<ResponseField name="updated_at" type="string (ISO 8601)" required>
  UTC timestamp of the most recent update to this case.
</ResponseField>

### Example response

```json theme={null}
{
  "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"
}
```