Examples

cURL Examples

Copy page

Complete cURL examples for all major Cortex API operations. These examples are ready to copy and paste.

Setup

Set your API configuration as environment variables:

Code
 
export CORTEX_URL="http://localhost:8000"
export CORTEX_API_KEY="your-api-key"

Health & Statistics

Health Check

Code
 
curl "$CORTEX_URL/health"

Get Statistics

Code
 
curl "$CORTEX_URL/api/stats" \
  -H "X-API-Key: $CORTEX_API_KEY"

---

Documents

Upload a Document

Code
 
# collection_id and start_processing are query parameters
curl -X POST "$CORTEX_URL/api/upload?collection_id=default&start_processing=true" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -F "file=@document.pdf"

Upload Without Processing (for bulk)

Code
 
# start_processing is a query parameter
curl -X POST "$CORTEX_URL/api/upload?start_processing=false" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -F "file=@document.pdf"

Process Pending Documents

Code
 
curl -X POST "$CORTEX_URL/api/documents/process-pending" \
  -H "X-API-Key: $CORTEX_API_KEY"

List Documents

Code
 
curl "$CORTEX_URL/api/documents" \
  -H "X-API-Key: $CORTEX_API_KEY"

List Documents in a Collection

Code
 
curl "$CORTEX_URL/api/documents?collection_id=research" \
  -H "X-API-Key: $CORTEX_API_KEY"

Get Document Details

Code
 
curl "$CORTEX_URL/api/documents/doc_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY"

Delete a Document

Code
 
curl -X DELETE "$CORTEX_URL/api/documents/doc_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY"

Reprocess a Document

Code
 
curl -X POST "$CORTEX_URL/api/documents/doc_abc123/reprocess" \
  -H "X-API-Key: $CORTEX_API_KEY"

Bulk Delete

Code
 
curl -X POST "$CORTEX_URL/api/documents/delete" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["doc_1", "doc_2", "doc_3"]}'

---

Custom Inputs

Add Q&A Pair

Code
 
curl -X POST "$CORTEX_URL/api/custom-input" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "qa",
    "title": "FAQ Entry",
    "question": "What is Cortex?",
    "answer": "Cortex is an agentic knowledge base."
  }'

Add Plain Text

Code
 
curl -X POST "$CORTEX_URL/api/custom-input" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "title": "Company Info",
    "content": "Cortex is a powerful knowledge management system..."
  }'

Add Markdown

Code
 
curl -X POST "$CORTEX_URL/api/custom-input" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "markdown",
    "title": "Technical Notes",
    "content": "# Overview\n\n## Features\n\n- Feature 1\n- Feature 2"
  }'

---

Search

Basic Search

Code
 
curl -X POST "$CORTEX_URL/api/search" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "machine learning", "limit": 10}'

Hybrid Search

Code
 
curl -X POST "$CORTEX_URL/api/search" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "neural networks",
    "limit": 20,
    "search_type": "hybrid"
  }'

Search in Collection

Code
 
curl -X POST "$CORTEX_URL/api/search" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "transformer architecture",
    "collection_id": "research",
    "limit": 10
  }'

Vector-Only Search

Code
 
curl -X POST "$CORTEX_URL/api/search" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "semantic similarity concepts",
    "search_type": "vector"
  }'

---

Ask AI (RAG)

Ask a Question

Code
 
curl -X POST "$CORTEX_URL/api/ask/stream" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the main findings?"}' \
  --no-buffer

Ask About a Collection

Code
 
curl -X POST "$CORTEX_URL/api/ask/stream" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Summarize the key points",
    "collection_id": "research"
  }' --no-buffer

Fast Mode

Code
 
curl -X POST "$CORTEX_URL/api/ask/stream" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the company mission?",
    "use_fast_search": true
  }' --no-buffer

Streaming Response

Code
 
curl -X POST "$CORTEX_URL/api/ask/stream" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Explain GraphRAG in detail"}' \
  --no-buffer

Deep Research (Agentic) Mode

Code
 
curl -X POST "$CORTEX_URL/api/ask/stream" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Compare the methodologies in papers A and B",
    "use_agentic": true
  }' --no-buffer

With Conversation History

Code
 
curl -X POST "$CORTEX_URL/api/ask/stream" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Can you elaborate on the third point?",
    "conversation_history": [
      {"role": "user", "content": "What are the benefits?"},
      {"role": "assistant", "content": "The main benefits are: 1) ..."}
    ]
  }' --no-buffer

---

Collections

Create Collection

Code
 
curl -X POST "$CORTEX_URL/api/collections" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Papers",
    "description": "Academic papers on AI and ML"
  }'

List Collections

Code
 
curl "$CORTEX_URL/api/collections" \
  -H "X-API-Key: $CORTEX_API_KEY"

Get Collection Details

Code
 
curl "$CORTEX_URL/api/collections/coll_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY"

Update Collection

Code
 
curl -X PUT "$CORTEX_URL/api/collections/coll_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "description": "Updated description"
  }'

Delete Collection

Code
 
curl -X DELETE "$CORTEX_URL/api/collections/coll_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY"

Move Documents

Code
 
curl -X POST "$CORTEX_URL/api/documents/move" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["doc_1", "doc_2"],
    "target_collection_id": "coll_def456"
  }'

---

Knowledge Graph

Get Graph Visualization

Code
 
curl "$CORTEX_URL/api/graph/visualization" \
  -H "X-API-Key: $CORTEX_API_KEY"

Search Entities

Code
 
curl "$CORTEX_URL/api/graph/entities?search=neural&limit=20" \
  -H "X-API-Key: $CORTEX_API_KEY"

Get Entity Details

Code
 
# Single entity is keyed by name (URL-encode it), not an opaque id
curl "$CORTEX_URL/api/graph/entity/Neural%20Network" \
  -H "X-API-Key: $CORTEX_API_KEY"

Get Subgraph

Code
 
curl -X POST "$CORTEX_URL/api/graph/subgraph" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_name": "Machine Learning",
    "max_depth": 2,
    "limit": 50
  }'

Find Duplicate Entities

Code
 
curl "$CORTEX_URL/api/entities/duplicates?threshold=0.85&limit=50" \
  -H "X-API-Key: $CORTEX_API_KEY"

Merge Duplicate Entities

Code
 
curl -X POST "$CORTEX_URL/api/entities/merge" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "canonical": "Machine Learning",
    "merge": ["machine learning", "ML"]
  }'

View Merge History

Code
 
curl "$CORTEX_URL/api/entities/merge-history?limit=20" \
  -H "X-API-Key: $CORTEX_API_KEY"

Delete All Entities

Code
 
curl -X DELETE "$CORTEX_URL/api/graph/entities" \
  -H "X-API-Key: $CORTEX_API_KEY"

---

Communities

Detect Communities

Code
 
curl -X POST "$CORTEX_URL/api/graph/communities/detect" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"min_community_size": 3}'

List Communities

Code
 
curl "$CORTEX_URL/api/graph/communities" \
  -H "X-API-Key: $CORTEX_API_KEY"

Get Community Details

Code
 
curl "$CORTEX_URL/api/graph/communities/comm_1" \
  -H "X-API-Key: $CORTEX_API_KEY"

Summarize Community

Code
 
curl -X POST "$CORTEX_URL/api/graph/communities/comm_1/summarize" \
  -H "X-API-Key: $CORTEX_API_KEY"

---

Background Tasks

Get Task Status

Code
 
curl "$CORTEX_URL/api/tasks/task_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY"

List Tasks

Code
 
curl "$CORTEX_URL/api/tasks" \
  -H "X-API-Key: $CORTEX_API_KEY"

Cancel Task

Code
 
curl -X DELETE "$CORTEX_URL/api/tasks/task_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY"

---

Admin - API Keys

Create API Key

Code
 
curl -X POST "$CORTEX_URL/api/admin/api-keys" \
  -H "X-API-Key: $CORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production App",
    "permissions": ["read", "write"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

List API Keys

Code
 
curl "$CORTEX_URL/api/admin/api-keys" \
  -H "X-API-Key: $CORTEX_API_KEY"

Revoke API Key

Code
 
curl -X POST "$CORTEX_URL/api/admin/api-keys/key_abc123/revoke" \
  -H "X-API-Key: $CORTEX_API_KEY"

Delete API Key

Code
 
curl -X DELETE "$CORTEX_URL/api/admin/api-keys/key_abc123" \
  -H "X-API-Key: $CORTEX_API_KEY"