Copy page

Using the API

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

Code
{
  "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

Code
{
  "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

Code
{
  "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 and the API Reference.