# Search, Natural Language Search, and Domain GenAI

The three capabilities are complementary.

| Capability | Best input | Returns | Typical use |
|---|---|---|---|
| Structured Search | Exact terms and filters | Paginated records | Precise retrieval |
| Natural Language Search | Descriptive phrase or question | Ranked records | Concept discovery |
| Domain GenAI | Analytical question | Answer, sources, and conversation metadata | Evidence-grounded synthesis |

## Structured Search

Use it when you know the terms, entity, country, date range, or component type.

```text
GET /v1/icd/videos?search=public%20safety&country=USA
```

When a Component ID is already known, use the direct `/by-component-id/{component_id}` route instead.

## Natural Language Search

Use it to find records related by meaning.

```text
GET /v1/icd/nl-search?search=emergency%20response%20and%20public%20safety
```

The response is a ranked set of records. It is not a generated answer.

## Domain GenAI

Use it when the application needs a concise answer supported by source records.

```http
POST /v1/icd/domain-genai
Content-Type: application/json

{
  "question": "What public safety themes appear in the available reporting?",
  "top_k": 5
}
```

Start without `conversation_id`. For a follow-up, send the opaque identifier returned by the prior successful turn.

## Cost and Behavior

- Search and retrieval operations are read-only.
- Domain GenAI creates or advances conversation context and consumes the applicable credits.
- Repeating a Domain GenAI request can create a new billable turn; do not retry it as though it were idempotent.
- Conversation deletion is non-billable and idempotent.

## Practical Pattern

1. Use search for discovery.
2. Retrieve the best records if full detail is needed.
3. Use Domain GenAI for synthesis.
4. Preserve `conversation_id` only while continuing the same conversation.