Core Concepts
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
- Discover with structured or Natural Language Search.
- Retrieve a selected record by UUID or known Component ID.
- Request media access only when the application needs it.
- Use Domain GenAI when synthesis adds value.
- Delete a conversation when the integration no longer needs its context.
Last modified on