Copy page

Using the API

Searching and Filtering

The IntelCenter API allows you to filter and refine results using query parameters across all datasets.

Two types of search are available:

• Keyword Search — precise, filter-driven queries
• Natural Language Search — conceptual, AI-assisted retrieval

---

Keyword Search Example

Code
curl --request GET \
  --url "https://api.intelcenter.com/v1/icdb/videos?entity=isis&country=iraq&page=1&per_page=10" \
  --header "Authorization: Bearer YOUR_API_KEY"

---

Natural Language Search Example

Code
curl --request GET \
  --url "https://api.intelcenter.com/v1/icd/nl-search?search=drone attacks near coastal infrastructure" \
  --header "Authorization: Bearer YOUR_API_KEY"

---

Supported Query Parameters (Keyword Search)

Parameter	Description
search	Full text search across indexed fields
entity	Filter by associated entity
country	Filter by primary country
date_from	Filter results on or after a date (YYYY-MM-DD)
date_to	Filter results on or before a date (YYYY-MM-DD)
page	Page number (default: 1)
per_page	Results per page (capped by your API key’s limit)
sort	Optional sorting (advanced usage)

---

Supported Query Parameters (Natural Language Search)

Parameter	Description
search	Natural language query
entity	Optional entity filter
country	Optional country filter
source_component	Filter by content type
top_k	Controls retrieval depth
page	Page number
per_page	Results per page

---

Pagination

Search results are paginated using page and per_page.

Example:

Code
?page=2&per_page=25

Response fields include:

• curPage — current page
• nextPage / prevPage — navigation
• perPage — results per page
• itemsTotal — total matching records
• pageTotal — total number of pages

If no pagination parameters are provided, default values will be used.

Note: The per_page value may be limited based on your API key tier.

---

Combining Filters

Multiple filters can be combined in a single request:

Code
/v1/icdb/videos?entity=isis&country=iraq&date_from=2024-01-01&date_to=2024-12-31

You can also combine full text search with filters:

Code
/v1/icdb/videos?search=attack&entity=isis&country=iraq

Natural Language Search also supports filters:

Code
/v1/icd/nl-search?search=missile launches&entity=iran&top_k=10

---

Dataset Compatibility

Keyword search is supported across all datasets:

• /v1/icd/videos
• /v1/icdb/videos
• /v1/icd/images
• /v1/icdb/images

Natural Language Search endpoints:

• /v1/icd/nl-search
• /v1/icdb/nl-search

---

Choosing the Right Search Method

Use Keyword Search when:

• You know exact terms (entity names, keywords)
• You need precise filtering
• You want predictable, structured results

Use Natural Language Search when:

• You are exploring a topic
• You need conceptual matching
• You want results across transcripts, analysis, and metadata

---

Performance Notes

• Indexed fields such as search, entity, and country are optimized for fast querying
• Pagination improves performance and response times
• Combining filters reduces result size and improves efficiency
• Natural Language Search may be slightly slower due to deeper retrieval

---

Default Behavior

• All query parameters are optional
• Results are returned in descending chronological order
• Parameter names use snake_case

---

Usage Limits

Search requests are subject to rate limits and quotas based on your API key.

• Requests per minute may be limited
• Daily and monthly quotas may apply

Natural Language Search may have different rate limits depending on your API key tier.

If limits are exceeded, the API will return a 429 Too Many Requests response.

---

MCP Usage

When using MCP endpoints, these same parameters are available but passed as structured inputs instead of query strings.

---

Tips

• Use keyword search for precision
• Use natural language search for discovery
• Combine filters to narrow results
• Use pagination to control response size
• Adjust top_k in NL search to balance depth vs performance