API Endpoints
All public REST endpoints are versioned under:
Code
ICD and ICDB use parallel route structures. Availability depends on the permissions assigned to the API key.
Search and Retrieval
| Method | ICD route | ICDB route | Purpose |
|---|---|---|---|
| GET | /v1/icd/videos | /v1/icdb/videos | Search video records |
| GET | /v1/icd/images | /v1/icdb/images | Search image records |
| GET | /v1/icd/videos/{uuid} | /v1/icdb/videos/{uuid} | Retrieve one video record |
| GET | /v1/icd/images/{uuid} | /v1/icdb/images/{uuid} | Retrieve one image record |
Component ID Lookup
Use these routes when a Component ID is already known.
| Method | ICD route | ICDB route |
|---|---|---|
| GET | /v1/icd/videos/by-component-id/{component_id} | /v1/icdb/videos/by-component-id/{component_id} |
| GET | /v1/icd/images/by-component-id/{component_id} | /v1/icdb/images/by-component-id/{component_id} |
A Component ID and a record UUID are different identifiers. Use the matching route for the identifier you hold.
Media Access
| Method | ICD route | ICDB route | Purpose |
|---|---|---|---|
| GET | /v1/icd/videos/{uuid}/player | /v1/icdb/videos/{uuid}/player | Retrieve an authorized video player URL |
| GET | /v1/icd/images/{uuid}/viewer | /v1/icdb/images/{uuid}/viewer | Retrieve an authorized image viewer URL |
Media URLs may expire. Request a fresh URL when needed.
Natural Language Search
| Method | ICD route | ICDB route |
|---|---|---|
| GET | /v1/icd/nl-search | /v1/icdb/nl-search |
Use the required search parameter and optional filters such as country, entity, source_component, and date bounds.
Domain GenAI
| Method | ICD route | ICDB route | Purpose |
|---|---|---|---|
| POST | /v1/icd/domain-genai | /v1/icdb/domain-genai | Start or continue a conversation |
| DELETE | /v1/icd/domain-genai/conversations/{conversation_id} | /v1/icdb/domain-genai/conversations/{conversation_id} | Delete a conversation |
Conversation deletion is available through REST and is not exposed as an MCP tool.
Geo Manifests
| Method | ICD route | ICDB route |
|---|---|---|
| GET | /v1/icd/videos/geo-manifest | /v1/icdb/videos/geo-manifest |
| GET | /v1/icd/images/geo-manifest | /v1/icdb/images/geo-manifest |
Geo Manifests support authorized filters, deterministic newest-first ordering, opaque cursor continuation, and JSON or GeoJSON output.
MCP
| Method | Route | Scope |
|---|---|---|
| POST | /mcp-icd | ICD tools |
| POST | /mcp-all | ICD and ICDB tools permitted for the API key |
See MCP Integration for tool names and behavior annotations.
For exact parameters, status codes, and schemas, use the API Reference.