# 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 experimental: measured on small gold sets (79 and 78 mentions), currently behind Google, F1 77.2 and 68.7 against 81.4 and 74.8), Wikidata identities, bring-your-own candidates. Made by WordLift. ## The one call POST https://api.wordlift.io/accounts/{accountId}/resolve Authorization: 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. - When the engine detects the mentions: "exclude_types": ["Date"] leaves out years and dates; a legal case name ("Brown v. Board of Education") is one mention, resolved to the case or unresolved, never to its parties; "mention_detection": "ner" | "vocabulary" | "both" chooses between the model and your dataset's own names and aliases (default "both" with a user dataset). - 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. The first call on your graph reads it: seconds for a small graph, a few minutes for a large one, and again after a few hours without calls. Meanwhile the answer is 503 with code "dataset_warming" and a Retry-After header; nothing is resolved or charged, so retry after the given seconds until it answers. - In an AI assistant, no key: the open demo is an MCP connector at https://mcp.wordlift.io/resolve (Streamable HTTP, no sign-in). One read-only tool, resolve_demo: text up to 600 characters, optional language, Wikidata identities, rate limited. Setup for Claude and ChatGPT: https://wordlift.io/resolve/#connect - 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. 503 "dataset_warming": your graph is being read, retry after Retry-After. Other 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/ - Moving from Azure Entity Linking (retiring 1 September 2028): https://docs.wordlift.io/developer-resources/resolve/migrate-from-azure-entity-linking/ - Azure Entity Linking alternative, side by side (identifier, behaviour when unsure, your own entities, free tier): https://wordlift.io/resolve/azure-entity-linking-alternative/ - 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. ## How it compares On VoxEL, a public multilingual news benchmark (ISWC 2018; 75 articles, 1,005 mentions in German, English, Spanish, French and Italian), on 19 October 2026: resolve() F1 91.8 with the mentions given and 87.0 finding them itself; Google Cloud Natural Language 89.9; Dandelion 85.7; Entity-Fishing 77.7 (mentions given); the first Wikidata search hit 75.5. Write-up, losses included: https://wordlift.io/blog/en/entity-linking-apis-compared/ ; results and the harness to rerun them: https://github.com/wordlift/content-analysis/tree/main/benchmarks/2026-10-19 Why taking the first Wikidata search hit breaks agents (61 wrong IDs in 351 names on the development sets, against 23 for resolve()): https://wordlift.io/blog/en/first-hit-wikidata-search/ ## 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.