> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.defdex.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.defdex.io/_mcp/server.

# Proposed corrections

Submit a sourced correction for human review. The API does not directly change research
or published data. Create a key with `corrections:submit`; add `corrections:read-own`
if the integration will monitor its submissions.

## Submit a proposal

`POST /api/v1/corrections` accepts a JSON body up to 16 KB. Include a stable
`Idempotency-Key` of 16–128 letters, digits, dots, underscores, colons or hyphens.
Create it once for the proposal and retain it until the outcome is known.

Example `proposal.json` (replace illustrative values with actual record identity and evidence):

```json
{
  "dataset": "organizations",
  "record_id": "OPAQUE_ID_FROM_ORGANIZATION_LIST",
  "explanation": "The official organization page reports a different legal name.",
  "sources": ["https://example.com/official-source"],
  "proposed_value": {"legal_name": "Example Legal Name"}
}
```

```sh
curl --fail-with-body 'https://app.defdex.io/api/v1/corrections' \
  --header "Authorization: Bearer $DEFDEX_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example-correction-request-001' \
  --data-binary @proposal.json
```

Use a unique key for each distinct proposal, rather than reusing the example globally.

| Input            | Constraint                                                                     |
| ---------------- | ------------------------------------------------------------------------------ |
| `dataset`        | Published dataset name                                                         |
| `record_id`      | Exact generic `record_id`; award convenience IDs also accepted for `awards`    |
| `explanation`    | Required, non-blank, at most 5,000 characters                                  |
| `sources`        | 1–10 HTTP(S) URLs, at most 2,048 characters each, without embedded credentials |
| `proposed_value` | Optional JSON; maximum nesting 32; no unsafe numeric integers                  |

Fields ending `_usd` require decimal strings. Submission validation is not proof that
the record exists or the proposed correction is correct; reviewers verify identity,
field meaning and evidence.

## Handle the receipt and retries

New proposals return **201** with the proposal object, including `id`, `status`,
submitted content and timestamps. There is no `data` wrapper on an individual receipt.
An equivalent normalized proposal retried by the same account with the same key returns
the original receipt with **200**. Different content under that key returns **409**.
Every admitted replay still counts toward request usage.

An account may have up to **100 open proposals** (`submitted`/`in_review`) and
**50 submissions per rolling day**. A storage-cap 429 may have no `Retry-After`;
waiting 60 seconds does not necessarily clear it. The shared API request limit also applies.

## Read review status

| Operation                                 | Access                                         |
| ----------------------------------------- | ---------------------------------------------- |
| `GET /api/v1/corrections`                 | Your account's proposals; `limit` and `cursor` |
| `GET /api/v1/corrections/{correction_id}` | One of your account's proposals                |

These reads require `corrections:read-own`. List pages have `data` and `next_cursor`,
and are ordered by proposal ID, not submission time. Individual reads return the
proposal directly. Other accounts' IDs return 404.

Statuses are `submitted`, `in_review`, `accepted`, `rejected` and `published`.
`reviewer_note` carries the user-visible review note when available. Acceptance and
publication are separate; publication follows the normal audited data build.