# Response Format

Successful IntelCenter API responses are JSON unless an endpoint explicitly returns another documented representation. Field presence varies by route and by the permissions of the API key.

## Structured Search

```json
{
  "itemsReceived": 1,
  "curPage": 1,
  "nextPage": null,
  "prevPage": null,
  "offset": 0,
  "perPage": 25,
  "itemsTotal": 1,
  "pageTotal": 1,
  "items": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "primary_id": 123456,
      "primary_date": "2026-03-12",
      "entity": "Example Entity",
      "primary_country": "USA",
      "title": "Example Title"
    }
  ]
}
```

Totals describe the authorized result set returned by that endpoint. They must not be interpreted as unrestricted dataset totals.

## Natural Language Search

```json
{
  "status": "ok",
  "itemsReceived": 1,
  "curPage": 1,
  "nextPage": null,
  "prevPage": null,
  "offset": 0,
  "perPage": 10,
  "retrieval_question": "public safety response",
  "source_component_filter": "video",
  "top_k": 10,
  "items": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "primary_id": 123456,
      "primary_date": "2026-03-12",
      "entity": "Example Entity",
      "primary_country": "USA",
      "source_component": "video",
      "source_database": "ICD",
      "score": 0.82,
      "title": "Example Title",
      "summary": "Example summary."
    }
  ]
}
```

## Component ID and UUID Detail

Direct lookup endpoints return one authorized detail record. A missing, unavailable, or unauthorized record may produce a not-found or access response without confirming whether content exists outside the caller's permissions.

## Domain GenAI

```json
{
  "status": "ok",
  "answer": "A supported answer based on the returned sources.",
  "response_id": "opaque-response-id",
  "sources": [
    {
      "source_database": "ICD",
      "source_component": "Video",
      "primary_id": 123456,
      "primary_date": "2026-03-12",
      "primary_country": "USA",
      "entity": "Example Entity",
      "sub_entity": "",
      "score": 0.72,
      "values": [],
      "metadata": {
        "source_database": "ICD",
        "source_component": "Video",
        "primary_id": 123456
      }
    }
  ],
  "conversation_id": "11111111-1111-1111-1111-111111111111",
  "conversation_expires_at": 1787538338294,
  "conversation_absolute_expires_at": 1787621138299,
  "usage": {
    "prompt_tokens": 1200,
    "output_tokens": 250,
    "total_tokens": 1450
  }
}
```

Use the typed `usage` object for new integrations. The `rag_prompt_tokens`, `rag_output_tokens`, and `rag_total_tokens` aliases are deprecated and retained temporarily for compatibility.

The `sources[].values` field is reserved and currently returns an empty array.

## Geo Manifest

JSON responses include `items`, traversal counters, `next_cursor`, `complete`, limit indicators, and `sort_order`. GeoJSON responses provide a `FeatureCollection` and equivalent traversal metadata.

The `primary_date_desc_component_id_desc` sort order means newest records are returned first, with Component ID descending as the deterministic order for records sharing a date.

A null exact-match field must not be treated as zero. Continue until `complete` is true or `next_cursor` is null.

## Errors

Error responses use the status code and shape documented for the operation. See [Errors and Status Codes](/errors) and the [API Reference](/api).