Copy page

AI & MCP · New

Natural Language Search

Natural Language Search allows you to query IntelCenter intelligence data using descriptive, conversational, or conceptual language.

Unlike traditional keyword search, Natural Language Search understands intent and meaning, returning results based on relevance across transcripts, visual analysis, summaries, and metadata.

---

Endpoints

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

---

When to Use Natural Language Search

Use Natural Language Search when:

• You are exploring a topic without exact keywords
• You want to search using questions or descriptions
• You need conceptual matching rather than exact terms
• You want to discover relevant records across multiple data sources

---

Example Request

Code
curl --request GET \
  --url "https://api.intelcenter.com/v1/icd/nl-search?search=recent drone activity by Houthis [Ansar Allah]&top_k=10" \
  --header "Authorization: Bearer YOUR_API_KEY"

---

Query Parameters

Parameter	Required	Description
search	Yes	Natural language query
entity	No	Filter by entity
primary_country	No	Filter by country
source_component	No	Filter by content type (video, image, etc.)
page	No	Page number
per_page	No	Results per page
top_k	No	Number of top matches to retrieve before pagination
date_from	No	Filter results on or after a date (YYYY-MM-DD)
date_to	No	Filter results on or before a date (YYYY-MM-DD)

---

How It Works

Natural Language Search:

1. Interprets the meaning of your query
2. Searches across:
   • Transcripts
   • Visual analysis
   • Audio analysis
   • Summaries
   • Metadata
3. Returns ranked results based on relevance

Each result includes a relevance score and context about where the match occurred.

---

Example Response (Simplified)

Code
{
  "items": [
    {
      "uuid": "11111111-1111-1111-1111-111111111111",
      "primary_date": "2026-03-12",
      "entity": "Houthis [Ansar Allah]",
      "score": 0.87,
      "section_type": "transcript",
      "summary": "Example matched content related to drone activity."
    }
  ],
  "curPage": 1,
  "perPage": 10
}

---

Key Differences vs Standard Search

Feature	Standard Search	Natural Language Search
Keyword matching	Yes	No
Conceptual understanding	Limited	Yes
Relevance scoring	Basic	Advanced
Best for discovery	Moderate	Strong
Best for precision	Strong	Moderate

---

Example Use Cases

• "Recent attacks involving drones in Yemen"
• "Media showing military parades by Houthis [Ansar Allah]"
• "Statements from leadership about regional conflict"
• "Visual evidence of weapons systems in use"

---

Pagination

Natural Language Search supports pagination:

Code
?page=2&per_page=10

top_k controls how many results are initially retrieved before pagination is applied.

---

Best Practices

• Use natural phrasing, not keywords
• Be specific when possible
• Combine with filters (entity, primary_country) for better results
• Use top_k to improve recall for broader queries

---

Limitations

• Results are based on relevance, not exact matches
• Scores are relative, not absolute
• Very broad queries may return mixed results

---

Recommended Workflow

1. Use Natural Language Search to explore a topic
2. Review relevant records
3. Use Domain GenAI to generate a synthesized answer

---

Tip

Natural Language Search is best for finding the right data.
Domain GenAI is best for understanding and summarizing it.