# Registry feedback and review

Strata maintains two independent registries. **Shorthands** help resolve names such as nicknames to exact catalog products. **Linkages** connect raw catalog products to graded identities with explicit language, printing and other variant constraints. Neither replaces verification of the physical item.

## How normal use improves the registry

Lookups can capture bounded identification evidence and initiate missing-link discovery. Explicit user corrections contribute additional evidence. Review checks identity and variant constraints before publishing a shared alias or verified link. Repeated requests, an agent's confidence, or a price similarity alone do not establish a match. A pending report never changes a live mapping immediately.

Read the official API on future lookups. Do not maintain a personal CSV, Discord thread or local crosswalk as the source of truth. Preserve returned references and mapping revisions, and reread the product when a comparison needs fresh linkage information. See [products and mappings](./products.md).

## Submit a correction

`POST /api/v1/identify` can return an account-bound `resultRef` when feedback storage is available. Keep it alongside the result shown to the user. References expire after 30 days; they cannot be shared across accounts. The current OAuth gateway does not expose feedback or confirmation operations. Use a personal API key for these routes; never send an OAuth token to a key-only route.

Send `POST /api/v1/feedback` with a bearer key, JSON body and a stable `Idempotency-Key` (8–128 letters, digits, dots, colons, underscores or hyphens):

```json
{"resultRef":"RESULT_UUID","registry":"shorthand","action":"correct_selection","correctedRef":{"productId":517045}}
```

| Field | Contract |
| --- | --- |
| `resultRef` | UUID returned with this account's original identify result. |
| `registry` | `shorthand` or `linkage`. |
| `action` | `correct_selection`, `wrong_identity`, `wrong_printing`, or `insufficient_evidence`. |
| `correctedRef` | Required only for `correct_selection`; omit for other actions. |
| `mappingRevision` | Optional nonnegative integer; must match the revision captured with the original result. |
| `comment` | Optional private evidence, at most 500 characters. Include only card details. |

For a shorthand correction, the positive integer `productId` must exist in the catalog. A raw-to-graded linkage correction uses an ALT asset reference:

```json
{"resultRef":"RESULT_UUID","registry":"linkage","action":"correct_selection","correctedRef":{"provider":"alt","entityType":"asset","id":"ALT_ASSET_UUID"}}
```

Replace placeholder UUIDs with returned identifiers. To report an incorrect link without proposing a replacement, use `wrong_identity` or `wrong_printing` and retain the observed mapping revision. Do not invent a result reference from a slab response: feedback currently depends on a reference captured by identification.

## What acknowledgement means

`202 pending_review` means the evidence was accepted, not that the correction was published. Keep the response reference. Feedback uses no lookup credits. Identical retries keep the same body and idempotency key; a new correction needs a new key.

A 404 means the result is missing, expired or belongs to another account. A 409 can indicate changed evidence or an idempotency conflict. A 503 means feedback is unavailable; the original identity and prices remain usable on their own merits. Do not repeatedly resubmit to influence review.

For a user's explicit catalog choice without a result reference, [suggest and confirm](./suggest.md) offers a separate pending shorthand-review path. Do not represent your own speculative choice as a human confirmation.

## Publication and limits

Review may accept, reject or leave evidence unresolved. Only an API-returned verified link with matching selectors supports cross-market pricing. Preserve raw and graded results independently when review is pending or a link is rejected. Automated review assistance does not give customer agents registry write or approval privileges. Internal review and database administration endpoints are not public integration surfaces.