---
title: "Free text → refs with confidence (the front door)"
method: GET
path: "/v2/entities/resolve"
tags: ["entities"]
---

# Free text → refs with confidence (the front door)

`GET /v2/entities/resolve`

## Request

- Base URL: `https://api.cardog.app`
- URL: `https://api.cardog.app/v2/entities/resolve`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

The ONE endpoint that accepts free text. Returns candidates ordered best-first; `best` is null when nothing clears the confidence floor — the API never guesses for you.

## Query parameters

- `q` string, required
- `domain` string
- `limit` integer

## Response `200`

Candidates with confidence

- EntityResolve
  - `query` string, required
  - `domain` string, nullable: Entity domain, e.g. "make", "model", "model-year", "fuel-type"
  - `candidates` object[], required
    - `ref` string, required: The entity ref ({domain}:{key}), the permanent identifier for this entity. Example: "make:tesla"
    - `domain` string, required: Entity domain, e.g. "make", "model", "model-year", "fuel-type"
    - `name` string, required: Display name, e.g. "Tesla"
    - `parentRef` string, nullable: Ref of the parent entity, for domains that nest (the parent of "model:mini/hardtop" is "make:mini")
    - `confidence` number, required: Match confidence, 0 to 1. Candidates are ordered highest first.
  - `best` object, nullable, required: The top candidate, only when its confidence clears the server's floor. Otherwise null, and the caller chooses.
    - `ref` string, required: The entity ref ({domain}:{key}), the permanent identifier for this entity. Example: "make:tesla"
    - `domain` string, required: Entity domain, e.g. "make", "model", "model-year", "fuel-type"
    - `name` string, required: Display name, e.g. "Tesla"
    - `parentRef` string, nullable: Ref of the parent entity, for domains that nest (the parent of "model:mini/hardtop" is "make:mini")
    - `confidence` number, required: Match confidence, 0 to 1. Candidates are ordered highest first.
  - `links` object: Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

## Other responses

- `400`: Invalid request — grammar failure or unknown-but-well-formed refs, NAMED in `refs`/`details`, with nearest-ref `suggestions` where computable. Never a fuzzy fallback.
- `401`: No valid credential (API key, session, or internal token)
- `429`: Per-minute rate limit exceeded
- `500`: Internal error

---

[API](https://skmtc.dev/cardog/apis/cardog-api-v2.md) · [All operations](https://skmtc.dev/cardog/apis/cardog-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/cardog/apis/cardog-api-v2/revisions/b9d48193126f?raw)