# Resolve a title

Turn a messy title (and optional author or ISBN) into ranked edition candidates.

MCP: `resolve_book` `{ "title": "Project Hail Mary", "author": "Andy Weir" }`

## When to use

- The user named a book
- You have a title string from another system and need a stable `fds_ed_…`

If you already have an ISBN, call [ISBN lookup](/docs/isbn) (or pass `isbn` here — it short-circuits). Do not use [search](/docs/search) as the first choice for a single known title.

## Request

```bash
curl -sS -H "Authorization: Bearer $FDS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Project Hail Mary","author":"Andy Weir","limit":5}' \
  https://api.fulldatasets.com/v1/match
```

| Body | Required | Notes |
|---|---|---|
| `isbn` | one of `isbn` or `title` | If valid and found, returns one `exact_isbn` candidate (score `1`) |
| `title` | one of `isbn` or `title` | Required when `isbn` is absent |
| `author` | no | Rank filter only. Not AND’d into title FTS |
| `kind` | no | `primary` \| `graphic` \| `any`. Default prefers the novel over comics / guides |
| `limit` | no | Default `10`, max `25` |

## Response `200`

```json
{
  "candidates": [
    {
      "entity_id": "fds_ed_37306635333664393039",
      "entity_type": "edition",
      "score": 1,
      "match_method": "exact_isbn",
      "book": {
        "id": "fds_ed_37306635333664393039",
        "title": "Project Hail Mary",
        "authors": ["Andy Weir"]
      }
    }
  ]
}
```

`match_method` is `exact_isbn` or `fuzzy_title_author`. **Prefer `candidates[0]`.**

Two-phase resolve: equality on folded `title_key` / `title_normalized` variants, then title-only `websearch_to_tsquery`. Author is a filter, not an FTS AND (so a missing author name cannot empty the result).

Same collapse as search: prefer `primary`, drop study guides and companions when a real title exists, one canonical edition per work. Pass `kind=graphic` (or put “graphic novel” in the title) when you want the comic.

Match hits Postgres (not the 24h point-lookup cache).

## Errors

| Status | `code` | When |
|---|---|---|
| `400` | `bad_request` | Invalid JSON, or neither `title` nor `isbn` |

## See also

- [Search](/docs/search) — browse / filters
- [Recommend](/docs/recommend) — similar works from seeds
- [Choose an endpoint](/docs/choose)