---
title: "Browse/search the entity registry (paged, capped)"
method: GET
path: "/v2/entities"
tags: ["entities"]
---

# Browse/search the entity registry (paged, capped)

`GET /v2/entities`

## Request

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

With no parameters at all, returns the domain index — every domain the registry serves, each with a `browse` link. With `domain`, one page of that domain's nodes. Page caps are dump-resistance: the registry is browsable for evaluation, not extractable by pagination.

## Query parameters

- `domain` string
- `q` string
- `page` integer
- `limit` integer

## Response `200`

With `domain`: one page of entity nodes (`items`). Without parameters: the domain index (`domains`).

- union
  - EntityBrowse
    - `items` 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")
    - `pagination` object, required
      - `page` integer, required
      - `limit` integer, required
    - `totalCount` integer, required
    - `links` object: Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}
  - EntityDomains
    - `domains` object[], required
      - `domain` string, required: Entity domain, e.g. "make", "model", "model-year", "fuel-type"
      - `count` integer, required: Entities currently in this domain
      - `links` object: Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}
    - `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)