# resolve_sunglasses

Turn what a user knows (brand, model name, code on the temple, size marking, lens) into exact catalog variants, or say precisely which detail is missing.

- REST: `POST https://sunglassesguides.com/api/v1/resolve` (OpenAPI operationId `resolve_sunglasses`)
- MCP: tool `resolve_sunglasses` on `https://sunglassesguides.com/mcp`
- Read-only: yes. It never changes anything outside this service.
- Market / units: US, USD, millimetres. Schema version 1.0.
- Support: implemented=true, data_covered=partial, externally_verified=false. Works over the published catalog only (Ray-Ban, Oakley, Maui Jim subset).

## When to use

- The user names a brand/model/code and you need the exact size and lens version.
- A model name is ambiguous (several sizes or lenses).

## When not to use

- The user only has a size marking like 52-18-140 and wants alternatives: call find_sunglasses directly.
- You already have a variant_id: call get_sunglasses_variant.

## Input

JSON body:

| Name | Type | Required | Range | Meaning |
|---|---|---|---|---|
| `query` | string | no | max 200 chars | Free text as the user wrote it, e.g. "Ray-Ban RB2140F 52" or "Holbrook OO9102 polarized". |
| `brand` | string | no | max 40 chars | Brand name, e.g. "Ray-Ban", "Oakley", "Maui Jim". |
| `model` | string | no | max 80 chars | Model name or model code, e.g. "Wayfarer", "RB2140", "Holbrook". |
| `manufacturer_code` | string | no | max 40 chars | Maker style/variant code as printed on the temple or product page, e.g. "RB2140F 901/58" or "OO9102-F455". |
| `size` | object | no |  | Known frame size, if printed on the temple. Fields: `lens_width_mm` (integer 30-80), `bridge_width_mm` (integer 8-30), `temple_length_mm` (integer 100-170). |
| `size_text` | string | no | max 40 chars | Temple size marking as text, e.g. "52-18-140" (frames print a small square between the first two numbers; that form is accepted too). |
| `lens` | string | no | max 60 chars | Lens color or lens name if known, e.g. "G-15", "Prizm Black". |
| `frame_color` | string | no | max 60 chars | Frame color if known. |
| `polarized` | boolean | no |  | Whether the user knows their lens is polarized. |
| `market` | string | no | max 8 chars | Market code. Only "US" is supported; anything else returns 422 UNSUPPORTED_MARKET. |
| `limit` | integer | no | min 1, max 10 | Maximum candidates returned when ambiguous. Default 5, max 10. |
| `expected_data_version` | string | no |  | data_version returned by an earlier call. If the catalog changed since, the call fails with DATA_VERSION_CHANGED instead of mixing old and new facts. |


## Output

The standard envelope (see [REST conventions](https://sunglassesguides.com/docs/rest.md)): `request_id`, `success`, `schema_version`, `data_version`, `data_mode`, `generated_at`, `request`, `result`, `sources`, `freshness`, `cache`, `next_actions`, and `error` on failure.

status RESOLVED (one variant), NEEDS_VARIANT (candidates + missing_fields), SIZE_ONLY_NOT_IDENTIFIABLE, NOT_FOUND_IN_CATALOG or OUT_OF_SCOPE. Never silently picks a size or lens.

`result.status` values: `RESOLVED`, `NEEDS_VARIANT`, `SIZE_ONLY_NOT_IDENTIFIABLE`, `NOT_FOUND_IN_CATALOG`, `OUT_OF_SCOPE`. `success:true` means the request was processed; it does not mean something matched.

## Sources and time

Each field carries `field_status`, `source_ids` and evidence excerpts; `sources[]` lists each cited source once with `retrieved_at`. `checked_at` is per record. See [freshness](https://sunglassesguides.com/docs/freshness.md).

## Permissions

Anonymous read-only trial without a key; optional API key for higher quotas. See [auth and quotas](https://sunglassesguides.com/docs/auth-and-quotas.md).

## Examples

### Ambiguous model (live)

```sh
curl -sS -X POST https://sunglassesguides.com/api/v1/resolve \
  -H 'Content-Type: application/json' \
  -d '{"query":"Ray-Ban Original Wayfarer"}'
```

```json
{
  "status": "NEEDS_VARIANT",
  "message": "10 variants match; the input does not identify one. Ask the user for: model, size_label, lens_width_mm, bridge_width_mm, lens_color, frame_color, polarized.",
  "candidate_count": 10,
  "missing_fields": [
    "model",
    "size_label",
    "lens_width_mm",
    "bridge_width_mm",
    "lens_color",
    "frame_color",
    "polarized"
  ],
  "size_options": [
    "50-22-?",
    "54-18-?",
    "52-22-?"
  ]
}
```

### Size only (cannot identify a model)

```sh
curl -sS -X POST https://sunglassesguides.com/api/v1/resolve \
  -H 'Content-Type: application/json' \
  -d '{"query":"52-18-140"}'
```

```json
{
  "status": "SIZE_ONLY_NOT_IDENTIFIABLE",
  "message": "A size marking (52-18-140) does not identify a brand or model: many frames share it. Use find_sunglasses to search by size, or add brand/model/code to identify the exact frame."
}
```

### Failure example

An empty body returns HTTP 422 `VALIDATION_FAILED` ("Provide at least one of ...").

## Related tools

- [find_sunglasses](https://sunglassesguides.com/docs/find_sunglasses.md)
- [get_sunglasses_variant](https://sunglassesguides.com/docs/get_sunglasses_variant.md)