# Domain GenAI

Domain GenAI answers analytical questions using authorized IntelCenter data. ICD and ICDB conversations are independent.

## Endpoints

| Dataset | Start or continue | Delete |
|---|---|---|
| ICD | `POST /v1/icd/domain-genai` | `DELETE /v1/icd/domain-genai/conversations/{conversation_id}` |
| ICDB | `POST /v1/icdb/domain-genai` | `DELETE /v1/icdb/domain-genai/conversations/{conversation_id}` |

Deletion is REST-only and is not exposed as an MCP tool.

## Start a Conversation

Omit `conversation_id` on the first turn.

```bash
curl --request POST \
  --url "https://api.intelcenter.com/v1/icd/domain-genai" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "question": "What public safety themes appear in the available reporting?",
    "top_k": 5
  }'
```

A successful response includes:

- `answer`
- `sources`
- `response_id`
- `conversation_id`
- `conversation_expires_at`
- `conversation_absolute_expires_at`
- `usage`

## Continue a Conversation

Send the opaque identifier returned by the preceding successful turn.

```json
{
  "question": "Which of those themes appears most frequently?",
  "conversation_id": "11111111-1111-1111-1111-111111111111",
  "top_k": 5
}
```

Conversation continuity supports follow-up questions and answers. For long conversations, restate critical context when necessary.

## Lifecycle

- The inactivity deadline is 60 minutes.
- The fixed maximum lifetime is 24 hours from conversation creation.
- A successful turn refreshes only the inactivity deadline.
- Failed or blocked requests do not extend the conversation.
- Expired, deleted, wrong-dataset, or wrong-credential identifiers return `conversation_unavailable`.
- Omit `conversation_id` to start over.

The two datasets do not share conversation identifiers or context.

## Delete a Conversation

```bash
curl --request DELETE \
  --url "https://api.intelcenter.com/v1/icd/domain-genai/conversations/11111111-1111-1111-1111-111111111111" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Success returns `204 No Content`. Deletion is non-billable and idempotent.

## Usage and Credits

A successful Domain GenAI turn consumes the applicable credits and returns the typed `usage` object. New integrations must use:

- `usage.prompt_tokens`
- `usage.output_tokens`
- `usage.total_tokens`

The `rag_prompt_tokens`, `rag_output_tokens`, and `rag_total_tokens` aliases are deprecated and remain temporarily for compatibility.

## MCP Behavior

Domain GenAI MCP tools are non-destructive but not read-only and not idempotent because they create or advance conversation context and consume credits. Clients should not automatically replay them.

## Answer Quality

Answers are grounded in the records returned as sources, but they can still be incomplete or inaccurate. Display the supporting sources, preserve dataset labels, and verify critical conclusions.