# Resolve free text

- Method: `GET`
- Path: `/resolve`
- Tier: Free
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-resolve/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-resolve

## Description

Resolves a free-text string — a ticker, a company, a coin, a person, an account, or a topic — into the exact selector needed to query it. Returns the best match plus ranked alternatives, each carrying asset_id with asset_class for assets and subject_id for both assets and non-asset subjects, so a caller never has to decide between /assets and /subjects before they know what they are holding. An exact symbol match always wins; assets otherwise rank ahead of non-asset subjects.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/resolve' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `query` (string, optional): Case-insensitive search across public identifiers and names.
- `limit` (integer, optional): Maximum results returned.

## Response

OK

- `best` (object, required): The single most likely match for the supplied query, or null when nothing matched.
- `best.asset_category` (string): Optional equity classification. Commodity and index instruments use commodity or index; ordinary equities omit this field.
- `best.asset_class` (string): Market class that namespaces the asset identifier.
- `best.asset_id` (string): Canonical public asset identifier. Equity identifiers are ticker symbols; crypto identifiers are canonical crypto IDs.
- `best.kind` (string, required): Which selector family the match belongs to: asset (use asset_id with asset_class) or subject (use subject_id).
- `best.matched_alias` (string): The name or alias that matched the query, so a caller can show why a lookup landed where it did.
- `best.name` (string, required): Human-readable name.
- `best.subject_id` (string): Canonical identifier for a non-asset person, account, or topic.
- `best.symbol` (string): Display ticker or market symbol.
- `matches` (array<object>, required): Ranked candidates for the supplied query, best first.
- `matches[].asset_category` (string): Optional equity classification. Commodity and index instruments use commodity or index; ordinary equities omit this field.
- `matches[].asset_class` (string): Market class that namespaces the asset identifier.
- `matches[].asset_id` (string): Canonical public asset identifier. Equity identifiers are ticker symbols; crypto identifiers are canonical crypto IDs.
- `matches[].kind` (string, required): Which selector family the match belongs to: asset (use asset_id with asset_class) or subject (use subject_id).
- `matches[].matched_alias` (string): The name or alias that matched the query, so a caller can show why a lookup landed where it did.
- `matches[].name` (string, required): Human-readable name.
- `matches[].subject_id` (string): Canonical identifier for a non-asset person, account, or topic.
- `matches[].symbol` (string): Display ticker or market symbol.
- `query` (string, required): The free-text string that was resolved, echoed back.

Media type: `application/json`

## JSON Response

```json
{
  "best": {
    "asset_category": "commodity",
    "asset_class": "equity",
    "asset_id": "NVDA",
    "kind": "asset",
    "matched_alias": "NVIDIA",
    "name": "NVIDIA Corporation",
    "subject_id": "text:artificial intelligence",
    "symbol": "NVDA"
  },
  "matches": [
    {
      "asset_category": "commodity",
      "asset_class": "equity",
      "asset_id": "NVDA",
      "kind": "asset",
      "matched_alias": "NVIDIA",
      "name": "NVIDIA Corporation",
      "subject_id": "text:artificial intelligence",
      "symbol": "NVDA"
    }
  ],
  "query": "nvidia"
}
```