Copy page

Using the API

Response Format

All IntelCenter API responses are returned in JSON format.

---

Search Response (Keyword 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": "Iraq",
      "title": "Example Title",
      "summary": "Example summary describing the content."
    }
  ]
}

---

Search Response (Natural Language Search)

Natural Language Search responses include additional relevance metadata.

Code
{
  "status": "ok",
  "itemsReceived": 1,
  "curPage": 1,
  "items": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "primary_id": 123456,
      "primary_date": "2026-03-12",
      "entity": "Example Entity",
      "primary_country": "Iraq",
      "source_component": "video",
      "score": 0.92,
      "summary": "Relevant content matching the query."
    }
  ]
}

---

Single Record Response

Code
{
  "uuid": "11111111-1111-1111-1111-111111111111",
  "primary_id": 123456,
  "primary_date": "2026-03-12",
  "entity": "Example Entity",
  "primary_country": "Iraq",
  "title": "Example Title",
  "summary": "Example summary describing the content.",
  "report": "Detailed analytical report text.",
  "transcript": "Full transcript text."
}

---

Media Access Response

Image Viewer

Code
{
  "status": "ok",
  "signed_url": "https://example.com/secure-url",
  "uuid": "11111111-1111-1111-1111-111111111111",
  "title": "Example Title"
}

Video Player

Code
{
  "status": "ok",
  "embed_url": "https://example.com/player",
  "expires": 1700000000,
  "uuid": "11111111-1111-1111-1111-111111111111",
  "title": "Example Title"
}

---

Domain GenAI Response

Domain GenAI responses are flexible and may include synthesized answers, supporting context, and structured metadata.

Code
{
  "answer": "Recent activity indicates increased use of naval drones...",
  "sources": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "title": "Example Source",
      "primary_date": "2026-03-12"
    }
  ]
}

Note: Response structure may vary depending on the query and model output.

---

Rate Limit / Quota Exceeded (429)

If your API key exceeds a rate limit or usage quota, the API will return:

Code
{
  "error": "quota_exceeded",
  "message": "This API key exceeded a usage or rate limit and the request was blocked.",
  "tier": "trial",
  "rate_limit": "domain-genai",
  "limits": {
    "daily_requests": 100,
    "monthly_requests": 1000
  },
  "action": "Wait for your quota to reset or contact IntelCenter if you need a higher usage allowance."
}

---

Forbidden (403)

Returned when your API key does not have access to the requested dataset or feature.

Code
{
  "error": "FORBIDDEN",
  "message": "You do not have access to this dataset or feature."
}

---

Unauthorized (401)

Returned when authentication fails.

Code
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

---

Notes

• All responses use JSON
• Field availability may vary by dataset and endpoint
• Natural Language and Domain GenAI responses may include additional metadata
• Pagination fields are only present on search endpoints
• Media URLs may be time-limited or signed

---

Error Handling

Always check the HTTP status code before processing the response.

• 200 — success
• 4xx — client error (invalid request, permissions, limits)
• 5xx — server error

Applications should handle non-200 responses gracefully and implement retry logic where appropriate.