# POST /v1/disputes

Create dispute

Create a dispute with a message of up to 5,000 Unicode characters. At most five unresolved disputes per publisher and one zone-quality dispute per zone in 24 hours. Subjects must belong to the publisher. Requires `publisher:write`; view-as is read-only. Rate limit tier: `write`.

- Required scope: `publisher:write`
- Rate limit: `write` — 20 requests per 60-second window per API key or web session

## Parameters

No parameters.

## Request body

```
{ message: string; subject_id?: integer | null; subject_type: "hold" | "adjustment" | "ivt" | "zone_quality" | "payout" | "other" }
```

## Response

```
{ amount_returned: string | null; first_response_at: string | null; first_response_due_at: string; id: integer; messages: { author_type: "publisher" | "admin"; body: string; created_at: string; id: integer }[]; opened_at: string; overdue: boolean; resolution: "upheld" | "rejected" | "partial" | null; resolve_due_at: string; resolved_at: string | null; status: "open" | "answered" | "resolved"; subject_id: integer | null; subject_type: "hold" | "adjustment" | "ivt" | "zone_quality" | "payout" | "other" }
```

## Errors

Rate-limited routes return `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the window ends); a 429 also carries `Retry-After`. The headers may be absent while the limiter is temporarily unavailable (requests are then let through).

| Status | Meaning |
|---|---|
| 401 | Missing, invalid or revoked API key. |
| 403 | The key lacks the required scope, or the operation is not allowed for this actor. |
| 429 | Rate limit exceeded; wait `Retry-After` seconds. |
| 400 | Default Response |
| 404 | Default Response |
| 409 | Default Response |

HTML documentation: https://agimone.com/en/developers/api/#create-dispute
API 2026-10
