<!-- Agent Datasets docs · Legal Entities REST endpoints · canonical: https://www.agentdatasets.com/docs/rest/entities · rendered from https://www.agentdatasets.com -->

# Legal Entities REST endpoints

GLEIF Legal Entity Identifier profiles and accounting-consolidation relationships from the Level-1 and Level-2 golden copies.

3 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md documents the same operations for MCP clients.

## GET /v1/entities/ownership

Entity Ownership

Return bounded current GLEIF Level-2 ownership evidence.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| lei | query | `string` | yes | — | — | Exact uppercase 20-character Legal Entity Identifier |
| direction | query | `"parents" \| "children"` | no | "parents" | — | Traverse toward parents or toward children |
| depth | query | `integer` | no | 1 | min 1, max 2 | Relationship hops to traverse |
| limit | query | `integer` | no | 50 | min 1, max 100 | Ownership links to return |
| cursor | query | `string \| null` | no | — | — | Opaque cursor from pagination.next_cursor |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/entities/ownership?lei=LEI"
```

### Response

`200` Successful Response — `EntityOwnershipResult`.

- `data` `EntityOwnershipData` (required) — Applied traversal and its bounded links plus reporting exceptions.
  - `lei` `string` (required)
  - `legal_name` `string | null` (required)
  - `direction` `"parents" | "children"` (required)
  - `depth` `integer` (required)
  - `links` `array<OwnershipLink>` (required)
    - `hop` `integer` (required)
    - `child_lei` `string` (required)
    - `child_name` `string | null` (required)
    - `parent_lei` `string` (required)
    - `parent_name` `string | null` (required)
    - `relationship_type` `string` (required)
    - `relationship_status` `string` (required)
    - `validity_start` `string (date-time) | null` (required)
    - `validity_end` `string (date-time) | null` (required)
    - `registration_status` `string` (required)
    - `initial_registration_date` `string (date-time) | null` (required)
    - `last_update_date` `string (date-time) | null` (required)
    - `validation_sources` `string | null` (required)
    - `validation_documents` `string | null` (required)
    - `validation_reference` `string | null` (required)
    - `source` `string` (required)
    - `license_tag` `string` (required)
    - `as_of` `string (date-time)` (required)
  - `exceptions` `array<OwnershipException>` (required)
    - `hop` `integer` (required)
    - `lei` `string` (required)
    - `legal_name` `string | null` (required)
    - `category` `string` (required)
    - `reason` `string` (required)
    - `reasons` `array<string>` (required)
    - `exception_references` `array<string>` (required)
    - `source` `string` (required)
    - `license_tag` `string` (required)
    - `as_of` `string (date-time)` (required)
- `meta` `EntitiesMeta` (required) — GLEIF provenance and interpretation shared by entity results.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
  - `unit` `"entity_record"`
  - `period` `"current"`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/entities/profile

Entity

Return one current GLEIF Level-1 legal-entity profile.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| lei | query | `string` | yes | — | — | Exact uppercase 20-character Legal Entity Identifier |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/entities/profile?lei=LEI"
```

### Response

`200` Successful Response — `EntityProfileResult`.

- `data` `EntityProfileData` (required) — One current GLEIF Level-1 legal-entity profile.
  - `lei` `string` (required) — Join key for funds_get_holdings data.holdings[].issuer_lei and any other record that carries the same 20-character LEI.
  - `legal_name` `string` (required)
  - `other_names` `array<string>` (required)
  - `previous_names` `array<string>` (required)
  - `legal_jurisdiction` `string` (required)
  - `entity_status` `string` (required)
  - `registration_status` `string` (required)
  - `registration_authority_id` `string | null` (required)
  - `registration_authority_entity_id` `string | null` (required)
  - `legal_address` `EntityAddress` (required) — The country and subdivision retained from a GLEIF address.
    - `country` `string | null` (required)
    - `region` `string | null` (required)
  - `headquarters_address` `EntityAddress` (required) — The country and subdivision retained from a GLEIF address.
    - `country` `string | null` (required)
    - `region` `string | null` (required)
  - `source` `string` (required)
  - `license_tag` `string` (required)
  - `as_of` `string (date-time)` (required)
- `meta` `EntitiesMeta` (required) — GLEIF provenance and interpretation shared by entity results.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
  - `unit` `"entity_record"`
  - `period` `"current"`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/entities/search

Entities Search

Search current GLEIF Level-1 legal-entity records.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| query | query | `string` | yes | — | — | Legal name, alias, previous name, or 20-character LEI |
| country | query | `string \| null` | no | — | — | Optional 2-letter legal-address country code |
| status | query | `"ACTIVE" \| "INACTIVE" \| null` | no | — | — | Optional GLEIF entity status |
| limit | query | `integer` | no | 10 | min 1, max 50 | Entity matches to return |
| cursor | query | `string \| null` | no | — | — | Opaque cursor from pagination.next_cursor |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/entities/search?query=QUERY"
```

### Response

`200` Successful Response — `EntitySearchResult`.

- `data` `EntitySearchData` (required) — Echoed filters and a bounded best-first page of entity matches.
  - `query` `string` (required)
  - `country` `string | null` (required)
  - `status` `"ACTIVE" | "INACTIVE" | null` (required)
  - `matches` `array<EntitySearchMatch>` (required)
    - `lei` `string` (required) — 20-character Legal Entity Identifier used by detail tools.
    - `legal_name` `string` (required)
    - `legal_jurisdiction` `string` (required)
    - `entity_status` `string` (required)
    - `registration_status` `string` (required)
    - `legal_address_country` `string | null` (required)
    - `score` `integer` (required)
    - `match_reason` `string` (required)
    - `source` `string` (required)
    - `as_of` `string (date-time)` (required)
- `meta` `EntitiesMeta` (required) — GLEIF provenance and interpretation shared by entity results.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
  - `unit` `"entity_record"`
  - `period` `"current"`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json