API reference · Query

Resolve entities

POST/v1/entities:resolve

Names and identifiers to entities, with ranked, explained candidates.

scope: read
auth: Bearer key
operationId: ResolveEntities
MCP tool: resolve_entity

Request body

application/json · ResolveRequest · no other fields

Request body fields
Field	Type	Required	Limits	Holds
mentions	Mention[]	yes	1 to 100 items
as_of	AsOfRequest	no
max_age_seconds	integer	no	1 to 315360000
mode	strict · standard · broad	no		Which items could be served. Each mode returns everything the one before it does.

Response

200 · ResolveResponse. A resolution per mention, or typed abstentions.

Response fields
Field	Type	Holds
response_id	ResponseID	A response's ID. It replays and compares that exact response.
status	answered · partial · abstained	Whether there is an answer.
as_of	AsOf	When the answer applies (valid_at), and what the record held then (known_at).
mode	strict · standard · broad	Which items could be served. Each mode returns everything the one before it does.
preset	string · nullable	The key's preset, if any.
items	Item[]	The cited facts.
abstentions	Abstention[]	Why part of the question has no answer.
negative_results	NegativeResult[]	What was searched, and found nothing.
withheld	Withheld[]	Items left out, by reason and count.
attributions	Attribution[]	Text to repeat where you show the data.
meta	Meta	The policy version, the index versions, and the milliseconds the server took.
resolutions	Resolution[]

Rate-limit headers

RateLimit-Limit: The bucket's size.
RateLimit-Remaining: Tokens left in it.
RateLimit-Reset: Seconds until it is full.

Problems

RFC 9457 application/problem+json. An abstention is not one of these: it is a 200.

Problems
HTTP	Code	When
400	INVALID_REQUEST	Malformed JSON, unknown fields, bad filter, limit exceeded
401	UNAUTHENTICATED	Missing, malformed, or revoked key
403	FORBIDDEN_SCOPE	The key lacks the required scope
413	PAYLOAD_TOO_LARGE	Body or upload over the limit
422	UNPROCESSABLE	Well-formed but semantically invalid
429	RATE_LIMITED	Rate limit or per-tenant model cap
500	INTERNAL, POLICY_ASSERT_FAILED, RESPONSE_UNREPLAYABLE	Server fault. The last two also alert
503	STORE_UNAVAILABLE, LLM_UNAVAILABLE, LOG_UNAVAILABLE	A dependency is down or a budget tripped
504	TIMEOUT	A deadline was exceeded

Sample

Request

POST /v1/entities:resolve
Content-Type: application/json

{
  "mentions": [
    {
      "text": "MOA NICKEL",
      "kind": "org"
    },
    {
      "identifier": {
        "scheme": "ofac_uid",
        "value": "3751"
      }
    }
  ]
}

Sample response · GET /v1/samples/resolve

{
  "abstentions": [],
  "as_of": {
    "known_at": "2026-10-28T14:34:53.187843Z",
    "valid_at": "2026-10-28T14:34:53.187843Z"
  },
  "attributions": [
    {
      "source_id": "ofac_sls",
      "text": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service"
    }
  ],
  "items": [],
  "meta": {
    "index_versions": {
      "ofac_sls": "01a182ef-71a0-7861-9595-c4ecfc82ba02"
    },
    "policy_version": 1,
    "server_ms": 1
  },
  "mode": "strict",
  "negative_results": [],
  "preset": null,
  "resolutions": [
    {
      "candidates": [
        {
          "basis": "fuzzy_name",
          "entity": {
            "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
            "kind": "org",
            "name": "MOA NICKEL SA",
            "redirected_from": null
          },
          "explanation": {
            "alias_coverage": 1,
            "contradicted": [],
            "corroborated": [],
            "matched": [
              "moa",
              "nickel"
            ],
            "query_coverage": 1,
            "strength": 1,
            "unmatched": []
          },
          "matched_on": "MOA NICKEL SA",
          "score": 1,
          "score_is_calibrated": false
        }
      ],
      "detail": {
        "code": "NAME_ONLY_MATCH"
      },
      "mention": {
        "kind": "org",
        "text": "MOA NICKEL"
      },
      "outcome": "resolved",
      "selection": "ambiguous"
    },
    {
      "candidates": [
        {
          "basis": "exact_id",
          "entity": {
            "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
            "kind": "org",
            "name": "MOA NICKEL SA",
            "redirected_from": null
          },
          "explanation": {
            "alias_coverage": 0,
            "contradicted": [],
            "corroborated": [],
            "matched": [
              "ofac_uid=3751"
            ],
            "query_coverage": 0,
            "strength": 0,
            "unmatched": []
          },
          "matched_on": "",
          "score": 1,
          "score_is_calibrated": false
        }
      ],
      "mention": {
        "identifier": {
          "scheme": "ofac_uid",
          "value": "3751"
        }
      },
      "outcome": "resolved",
      "selected": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
      "selection": "single"
    }
  ],
  "response_id": "resp_06GR5VVKGNXB145ZZQT7PXWW3C",
  "status": "answered",
  "withheld": []
}