# WordLift resolve()

> Map an entity mention to an identity in a dataset, or get `unresolved`. Multilingual (en, it, fr, de, es, pt; ja and zh answer too but are not measured yet), Wikidata identities, bring-your-own candidates. Made by WordLift.

## The one call

POST https://api.wordlift.io/accounts/{accountId}/resolve
Authorization: Key <WordLift API key>
# accountId: the accountId field of GET https://api.wordlift.io/accounts/me with the same key.
Content-Type: application/json

{"text": "Apple opened a new store in Rome.",
 "language": "en",
 "mentions": [{"text": "Apple", "start": 0, "end": 5,
               "candidates": [{"id": "wd:Q312"}, {"id": "wd:Q89"}]}],
 "include": ["candidates"]}

Response, one item per mention:
{"mentions": [{"text": "Apple", "start": 0, "end": 5, "status": "resolved",
               "entity": {"id": "wd:Q312", "label": "Apple Inc.", "types": ["Organization"],
                          "same_as": ["https://www.wikidata.org/entity/Q312"]},
               "score": 0.99}],
 "dataset_uri": "wikidata://public", "language": "en", "engine": "content-analysis-v3"}

Rules an agent should rely on:
- "status" is "resolved" or "unresolved". Unresolved is a valid answer, not an error; its "reason" is one of no_suitable_candidate, no_candidates, type_conflict, low_relevance. Never substitute a guess.
- Omit "mentions" and the engine detects them. Omit a mention's "candidates" and the engine retrieves against the dataset. Supply candidates and the answer is one of them or unresolved.
- Identities may be given as Q312, wd:Q312 or https://www.wikidata.org/entity/Q312; they come back in the form you sent.
- "score" is the relevance of the returned entity in [0, 1], not a calibrated probability; each mention also carries "signals": {"path": "fast" | "reranked" | "vocabulary", "retrieval_prior", "match_probability", "rescued"}. Compare scores across mentions only within the same path. When the decision layer ships, "score" will mean confidence in the final decision and the technical numbers stay in "signals".
- Spans are character offsets into "text" and must match exactly (422 otherwise). Text up to 100,000 characters.
- Your own world: "dataset_uri": "wordlift://dataset/me" resolves against your WordLift knowledge graph (read with your key); or send "dataset": {"entities": [{"id", "name", "aliases", "description", "types", "same_as"}]} (up to 5,000) and the answer is one of your ids or unresolved. Local entity first: "dataset_uri": "wordlift://dataset/me,wikidata://public" tries your graph, then Wikidata, per mention; each mention reports the world that answered in its own "dataset_uri". With a user dataset, per-mention candidates are not accepted.
- Your own data, step by step (graph, inline vocabulary, local-first, the sameAs bridge, limits): https://github.com/wordlift/content-analysis/blob/main/docs/your-own-data.md
- 401: missing or invalid key. 422: bad span, unknown identity form, unsupported dataset_uri, invalid inline dataset, or candidates sent together with a user dataset. 5xx or timeout: treat as unresolved and retry later.

## Try it without a key
- POST https://resolve.wordlift.io/demo/resolve with {"text": "...", "language": "en"} and optionally "mentions" (up to 16 spans). No key. Same engine, same answer shape as the one call.
- Limits: 600 characters of text, 10 requests a minute per IP (429 with retry_after_s beyond that), no service level. It is the landing page's tester, kept open so you can see a real answer before asking for a key. For anything beyond a look, get a key: it is free for individual developers and comes with 1,000 requests a month.
- Three live comparisons, with and without resolve(), on the same open endpoint: https://wordlift.io/resolve/demos/ (news routing, a financial report, content classification; synthetic texts, real identities and real NIL decisions). Edit the mentions and run both agents.

## Machine-readable contract
- Developer guide: https://docs.wordlift.io/developer-resources/resolve/
- API reference: https://docs.wordlift.io/api/resolve/resolve-api/
- OpenAPI document: https://raw.githubusercontent.com/wordlift/content-analysis/main/docs/openapi.resolve.json
- Health, no auth: https://resolve.wordlift.io/health

## Clients
- Python: pip install "resolve-pipeline @ git+https://github.com/wordlift/content-analysis.git" ; from resolve_pipeline import WordLiftResolver
- TypeScript/JavaScript: npm install @wordlift/resolve ; import { WordLiftResolver } from "@wordlift/resolve"
- Command line: python -m resolve_pipeline "text" (needs WL_KEY)
- Source, contract and gold sets: https://github.com/wordlift/content-analysis (Apache-2.0)
- Command line with your data: python -m resolve_pipeline "text" --dataset-uri wordlift://dataset/me,wikidata://public ; --dataset my-entities.json

## Getting a key
Keys are WordLift API keys. Request a free one at https://wordlift.io/resolve/#access: name, email, use case; the key arrives by email. Free for individual developers, 1,000 requests a month (a call counts as one request, plus one per 1,000 characters of text). An agent cannot sign up by itself: ask the person you work for to request the key and put it in WL_KEY. Existing WordLift customers use their account key.

## Status of the decision layer
The endpoint runs WordLift's production linker today. A stricter NIL-safe layer is released per language only after a frozen held-out gate (precision >= 99%, coverage >= 90%, false resolution under forced NIL <= 2%); results so far are published at https://wordlift.io/resolve/#benchmarks with every miss.