> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-ad5578da.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> You can generate and manage API keys from your Cortex Dashboard. All endpoints require an API key sent as a Bearer token in the Authorization header.

Welcome to the Cortex SDK API Reference. This section documents every available endpoint and how to interact with them to power AI apps and agents with intelligent memory and retrieval.

> Base URL: `https://api.usecortex.ai`
>
> Contact us to get your API key at [founders@usecortex.ai](mailto:founders@usecortex.ai)

```mdx theme={null}
Authorization: Bearer <your_api_key>
```

### Multi-Tenant Architecture

All endpoints support Cortex's hierarchical multi-tenant system using `tenant_id` (primary organization) and `sub_tenant_id` (departments/teams). This enables secure data isolation for enterprise applications.

<Note>
  **Default Sub-Tenant Behavior**: When you create a tenant, Cortex automatically creates a **DEFAULT sub-tenant** that acts as a global space. If you don't specify a `sub_tenant_id` in your API calls, your data will be stored in this default sub-tenant. This is perfect for organization-wide data that should be accessible across all departments.
</Note>

<Info>
  **Creating Additional Sub-Tenants**: Sub-tenants are created automatically when you first use a new `sub_tenant_id` that doesn't exist yet. No separate API call is required. For B2C applications, use user IDs as sub-tenant IDs (e.g., `sub_tenant_id: "user_12345"`). For B2B applications, use descriptive department names (e.g., `sub_tenant_id: "engineering"`).
</Info>

[Learn more about multi-tenancy](/essentials/multi-tenant) | [Learn more about metadata](/essentials/metadata)

### Metadata Architecture

Cortex provides a powerful two-tier metadata system for precise document organization and filtering:

#### **Tenant Metadata** (`tenant_metadata`)

* **Purpose**: Organization-level metadata that applies consistently across all documents within a tenant
* **Immutability**: Keys are **immutable** and can only be set when creating a tenant via `tenant_metadata_schema`
* **Best For**: Fixed organizational attributes like department, compliance framework, data classification, or business unit
* **Example**: `{"department": "Engineering", "compliance_framework": "SOC2", "data_classification": "internal"}`

#### **Document Metadata** (`document_metadata`)

* **Purpose**: Document-specific metadata that varies from document to document
* **Flexibility**: **Fully mutable** and flexible - can be different for each document
* **Best For**: Variable document attributes like title, author, creation date, document type, or custom tags
* **Example**: `{"title": "API Security Guidelines", "author": "Dr. Sarah Chen", "document_type": "technical_specification"}`

<Note>
  **Metadata Filtering**: Use both metadata types in your search queries to filter sources by specific criteria. For example, find all engineering documents authored by specific team members or filter by document type and compliance status.
</Note>

### **Data Ingestion**

Upload and import content into Cortex from various sources.

* `/upload/upload_document` — Upload single documents
* `/upload/upload_text` — Upload text/markdown content
* `/upload/upload_app_sources` — Import from workplace apps (Gmail, Slack, etc.)
* `/upload/scrape_webpage` — Scrape and index web content
* `/upload/verify_processing` — Check upload processing status
* `/upload/batch_upload` — Upload multiple files at once

### **Search & Query**

Retrieve answers and information from your knowledge base.

* `/search/qna` — Main search endpoint with AI-powered responses. Supports optional `metadata` parameter to filter sources by `source_title` or `source_type`.
* `/search/retrieve` — Hybrid search without AI generation. Returns structured search results for custom processing.
  – `/search/full-text-search` – Perform a full text search without AI generation. Allows you to use operators like logical `AND`, `OR`

### **Knowledge Management**

Browse, fetch, and manage your knowledge base.

* `/list/sources` — Browse all indexed sources
* `/list/sources_by_id` — Get specific sources by ID
* `/fetch/fetch_content` — Retrieve file content and download URLs
* `/delete_source` — Remove sources from knowledge base

### **Update & Upsert**

Update existing content and embeddings. If a `source_id` does not exist, these endpoints upsert (create or update).

* `/upload/update_text` — Upsert markdown/text content by `source_id`
* `/upload/update_document` — Upsert a file/document by `source_id`
* `/upload/update_webpage` — Re-scrape and upsert a webpage by `source_id` and `web_url`
* `/upload/update_embeddings` — Update existing embeddings by `chunk_id` within a batch/source

### **Embeddings**

Manage and query pre-computed embeddings.

* `/upload/upload_embeddings` — Upload embeddings and get generated `chunk_ids`
* `/embeddings/search` — Vector similarity search; returns nearest `chunk_ids` and scores
* `/embeddings/retrieve_by_ids` — Retrieve embedding vectors for specific `chunk_ids`
* `/embeddings/delete` — Delete embeddings by `chunk_id`

### **Tenant Management**

Create and monitor tenants for multi-tenant setups.

* `/user/create_tenant` — Create a tenant with optional `tenant_metadata_schema` to define immutable tenant-level metadata fields
* `/embeddings/create_tenant` — Create an embeddings-only tenant (sets `sub_tenant_id = tenant_id`); use when directly uploading/searching embeddings
* `/tenant/stats` — Get tenant stats (object count, vector dimension, identifiers)

<Note>
  **Tenant Metadata Schema**: When creating a tenant, you can define a `tenant_metadata_schema` that specifies which metadata keys are allowed at the tenant level. These keys become immutable and can only be set during tenant creation. Document metadata remains fully flexible and can be set per document during upload.
</Note>

### **User Memory**

Personalize, retrieve, and manage user-specific AI memories for advanced agentic workflows.

* `/user_memory/list_user_memories` — Browse user memories
* `/user_memory/retrieve_user_memory` — Get specific user memories
* `/user_memory/add_user_memory` — Manually add user-specific memories
* `/user_memory/generate_user_memory` — AI-generated personalized memories
* `/user_memory/delete_user_memory` — Remove user memories

## 💡 Best Practices

* Use **sub-tenants** to support multi-user isolation in B2B use cases.
* **Design your metadata strategy**: Use `tenant_metadata` for fixed organizational attributes (department, compliance) and `document_metadata` for variable document attributes (title, author, type).
* **Plan tenant metadata carefully**: Remember that tenant metadata keys are immutable once set during tenant creation.
* Leverage **metadata filtering** in search queries for precise document retrieval and agentic workflows.
* Tune **search\_alpha** and **recency\_bias** to control relevance.
* Enable **highlight\_chunks** for chunk-level citations.

***