Base URL: https://api.usecortex.ai
Contact us to get your API key at [email protected]
Multi-Tenant Architecture
All endpoints support Cortex’s hierarchical multi-tenant system usingtenant_id (primary organization) and sub_tenant_id (departments/teams). This enables secure data isolation for enterprise applications.
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.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").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"}
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.
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 optionalmetadataparameter to filter sources bysource_titleorsource_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 logicalAND,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 asource_id does not exist, these endpoints upsert (create or update).
/upload/update_text— Upsert markdown/text content bysource_id/upload/update_document— Upsert a file/document bysource_id/upload/update_webpage— Re-scrape and upsert a webpage bysource_idandweb_url/upload/update_embeddings— Update existing embeddings bychunk_idwithin a batch/source
Embeddings
Manage and query pre-computed embeddings./upload/upload_embeddings— Upload embeddings and get generatedchunk_ids/embeddings/search— Vector similarity search; returns nearestchunk_idsand scores/embeddings/retrieve_by_ids— Retrieve embedding vectors for specificchunk_ids/embeddings/delete— Delete embeddings bychunk_id
Tenant Management
Create and monitor tenants for multi-tenant setups./user/create_tenant— Create a tenant with optionaltenant_metadata_schemato define immutable tenant-level metadata fields/embeddings/create_tenant— Create an embeddings-only tenant (setssub_tenant_id = tenant_id); use when directly uploading/searching embeddings/tenant/stats— Get tenant stats (object count, vector dimension, identifiers)
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.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_metadatafor fixed organizational attributes (department, compliance) anddocument_metadatafor 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.