# Choosing the Right Endpoint

Select the narrowest capability that matches the task.

| You have or need | Use | Why |
|---|---|---|
| A Component ID | Component ID lookup | Direct and unambiguous |
| A record UUID | Detail endpoint | Retrieves one record |
| Exact terms and filters | Structured search | Precise filtering and paging |
| A descriptive concept | Natural Language Search | Ranked conceptual discovery |
| An analytical question | Domain GenAI | Evidence-grounded synthesis |
| Mappable authorized records | Geo Manifest | Cursor-based JSON or GeoJSON |
| Tool discovery in an assistant or agent | MCP | Structured tools with behavior annotations |

## Component ID Lookup

Use a direct route whenever the Component ID is known:

- `/v1/icd/videos/by-component-id/{component_id}`
- `/v1/icd/images/by-component-id/{component_id}`
- Parallel ICDB routes use the same structure.

Do not route a known Component ID through keyword search.

## Structured Search

Use video or image search when you know terms or filters and need records:

- `/v1/{dataset}/videos`
- `/v1/{dataset}/images`

## Natural Language Search

Use `/v1/{dataset}/nl-search` for conceptual discovery. It returns ranked records rather than a generated answer.

## Domain GenAI

Use `/v1/{dataset}/domain-genai` when the desired result is an answer supported by source records. Use `conversation_id` only for follow-up turns that belong to the same conversation.

## Recommended Workflow

1. Discover with structured or Natural Language Search.
2. Retrieve a selected record by UUID or known Component ID.
3. Request media access only when the application needs it.
4. Use Domain GenAI when synthesis adds value.
5. Delete a conversation when the integration no longer needs its context.