All docs Nebula docs All endpoints Interactive docs Markdown OpenAPI JSON

REST API
Other

Resolve free text

GET /resolve

ResolveIdentity

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.

Parameters

query string QUERY

Case-insensitive search across public identifiers and names.

Example:NVIDIA

limit integer QUERY

Maximum results returned.

Example:25

cURL Example

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

Responses

200 OK

400 Bad Request

401 Unauthorized

402 Credit balance exhausted

403 Forbidden

404 Not Found

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Media type application/json

best

object required

The single most likely match for the supplied query, or null when nothing matched.

best.asset_category

string optional

Optional equity classification. Commodity and index instruments use commodity or index; ordinary equities omit this field.

best.asset_class

string optional

Market class that namespaces the asset identifier.

best.asset_id

string optional

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 optional

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 optional

Canonical identifier for a non-asset person, account, or topic.

best.symbol

string optional

Display ticker or market symbol.

matches

array<object> required

Ranked candidates for the supplied query, best first.

matches[].asset_category

string optional

Optional equity classification. Commodity and index instruments use commodity or index; ordinary equities omit this field.

matches[].asset_class

string optional

Market class that namespaces the asset identifier.

matches[].asset_id

string optional

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 optional

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 optional

Canonical identifier for a non-asset person, account, or topic.

matches[].symbol

string optional

Display ticker or market symbol.

query

string required

The free-text string that was resolved, echoed back.

{
  "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"
}