Base URL: https://api.usecortex.ai

Contact us to get your API key at founders@usecortex.ai

All endpoints require an API key sent as a Bearer token in the Authorization header.

Authorization: Bearer <your_api_key>

​
Prerequisites

  • Node.js / Python (or any backend language)
  • Basic knowledge of HTTP requests
  • An API key from Cortex (Authorization: Bearer <your_api_key>)
  • A document or webpage you want your AI to read

​
Step 1: Upload Your Knowledge Source

You can upload:

  • A public webpage
  • A document (PDF, DOCX, etc.)
  • Multiple documents in bulk

​
Option A: Upload a document

POST /upload/upload_document

Form Data:

  • file: your document
  • tenant_id: your unique tenant ID

​
Option B: Upload a webpage

POST /upload/scrape_webpage

curl -X POST 'https://api.usecortex.ai/upload/scrape_webpage?web_url=https://example.com&tenant_id=your_tenant_id' \
  -H "Authorization: Bearer <your_api_key>"

​
Step 2 (Optional): Verify Processing

Check if the document is fully indexed:

POST /upload/verify_processing?file_id=YOUR_FILE_ID

Returns success once the document is ready for querying.

​
Step 3: Ask Questions Using the AI Retrieval API

POST /search/qna

Request Body:

{
  "question": "What did the document say about pricing?",
  "session_id": "user-session-123",
  "tenant_id": "your_tenant_id",
  "context_list": ["optional_specific_file_id"],
  "ai_generation": true,
  "highlight_chunks": true,
  "tenant_metadata": {"source_title": "contract.pdf"},
  "document_metadata": {"source_title": "contract.pdf"}
}

Example (cURL):

curl -X POST 'https://api.usecortex.ai/search/qna' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Summarize the contract terms",
    "session_id": "user-123-session",
    "tenant_id": "your_tenant_id",
    "tenant_metadata": {"source_title": "contract.pdf"},
    "document_metadata": {"source_title": "contract.pdf"}
  }'

​
Step 5: Display the Answer in Your App

You’ll get a JSON response like:

{
  "answer": "The contract specifies a 12-month term with a 30-day opt-out period...",
  "sources": [...],
  "chunks": [...]
}

Render the answer in your UI and include clickable citations if desired. Citations can reference:

  • Source filename (e.g., contract.pdf)
  • Page number
  • Snippet preview

If available, use the bounding_box to enable clickable highlights or coordinate-based jumping in PDFs.

You can use the tenant_metadata and document_metadata parameters to restrict the context to only sources matching a specific title or type. For example, { "source_title": "contract.pdf" } will only use sources with that title for answering the question.

​
Step 6: Iterate (Optional)

Fine-tune the user experience with:

  • AI response (true or false): Lets you decide if you only want the retrieved context or the AI generated response to user queries using retrieved context
  • search_alpha (0-1): Prioritize keyword vs. semantic match. An Alpha of “1” means semantic match. An Alpha of “0” means exact keyword match
  • recency_bias (0-1): Control how much you want to favour newly added knowledge. 1 you strongly favour recently added knowledge. 0 means freshness of knowledge doesn’t matter.
  • highlight_chunks: Get the actual context/chunks can be used for generating answers for RAG or Agentic purposes
  • stream: for real-time, streaming answers

​
🧩 Optional Extensions

  • Batch Upload: /upload/batch_upload for multiple files
  • Delete Memory: /delete_memory to remove documents
  • List Sources: /list/sources to display all uploaded documents