SDKs - Node and Python

Official TypeScript/Node.js and Python SDKs so that you can integrate Cortex AI into your application with ease.

Get started with our fully-typed SDKs that provide a seamless developer experience for integrating Cortex AI into your applications.

Installation

TypeScript / Node.js

npm i @usecortex_ai/node

Client Setup

TypeScript

import { CortexAIClient } from "@usecortex_ai/node";

const client = new CortexAIClient({
  token: process.env.CORTEX_API_KEY,
});

Always use environment variables for API keys. Never hardcode credentials in your source code.

Python developers: We provide both synchronous and asynchronous clients. Use AsyncCortexAI for async/await patterns and CortexAI for traditional synchronous operations.

SDK Method Structure & Type Safety

Our SDKs follow a predictable pattern that mirrors the API structure while providing full type safety:

Method Mapping: client.<group>.<function_name> mirrors api.usecortex.ai/<group>/<function_name>

For example: client.upload.uploadText() corresponds to POST /upload/upload_text

Input and Output Type Matching

The SDKs provide exact type parity with the API specification:

• Request Parameters: Every field documented in the API reference (required, optional, types, validation rules) is reflected in the SDK method signatures
• Response Objects: Return types match the exact JSON schema documented for each endpoint
• Error Types: Exception structures mirror the error response formats from the API
• Nested Objects: Complex nested parameters and responses maintain their full structure and typing

Language Conventions:

• TypeScript: camelCase method names (uploadText, getAll) with full TypeScript interfaces
• Python: snake_case method names (upload_text, get_all) with type hints and dataclasses

This means you can rely on your IDE’s autocomplete and type checking. If a parameter is optional in the API docs, it’s optional in the SDK. If a response contains a specific field, your IDE will know about it.

Getting Started: Complete Workflow

Let’s walk through a complete example from creating a tenant to searching your data.

Step 1: Create a Tenant

TypeScript

async function createTenant() {
  const tenantCreationResponse = await client.user.createTenant({
    tenant_id: "my-company"
  });
  return tenantCreationResponse;
}

For a more detailed explanation of tenant creation, including metadata schemas, sub-tenant management, and advanced configuration options, refer to the Create Tenant endpoint documentation.

Step 2: Index Your Data

Now let’s upload some content to make it searchable:

TypeScript

// Upload text content
async function uploadText() {
  const res = await client.upload.uploadText({
    tenant_id: "my-company",
    sub_tenant_id: "engineering",
    body: {
      content: "Our API rate limits are 1000 requests per minute for premium accounts.",
      file_id: "api-docs-rate-limits",
      tenant_metadata: { sub_tenant_id: "engineering" }
    }
  });
  return res;
}

// Upload a document file
async function uploadFile() {
  const uploadResult = await client.upload.uploadDocument({
    file: fs.readFileSync("company-handbook.pdf"),
    tenant_id: "my-company",
    sub_tenant_id: "hr",
    file_id: "doc_q1_summary"
  });
  return uploadResult;
}

For a more detailed explanation of document upload, including supported file formats, processing pipeline, metadata handling, and advanced configuration options, refer to the Upload Document endpoint documentation.

Step 3: Search and Retrieve

TypeScript

// Semantic search with retrieval
const results = await client.search.retrieve({
  query: "What are the API rate limits?",
  tenant_id: "my-company",
  sub_tenant_id: "engineering",
  max_chunks: 10
});

// List all sources
const allSources = await client.sources.getAll({
    tenant_id: "my-company",
    sub_tenant_id: "engineering"
});

// Get specific sources by ID
const specificSources = await client.sources.getByIds({
  tenant_id: "my-company",
  sub_tenant_id: "engineering",
  source_ids: ["api-docs-rate-limits", "company-handbook"]
});

For a more detailed explanation of search and retrieval, including query parameters, scoring mechanisms, result structure, and advanced search features, refer to the Search endpoint documentation.

Special Endpoints

List Sources

The /list endpoints use special naming in the SDKs for better developer experience:

• /list/sources → sources.getAll() / sources.get_all()
• /list/sources_by_id → sources.getByIds() / sources.get_by_ids()

This avoids conflicts with language keywords while providing intuitive method names.

Type Safety

All SDKs are fully typed with TypeScript definitions and Python type hints. Your IDE will provide:

• Autocomplete for all method names and parameters
• Type checking for request and response objects
• Inline documentation for each parameter
• Error prevention through compile-time validation

Error Handling

Both SDKs throw exceptions for API errors. The error objects contain the same structure as documented in our Error Responses section.

The Complete Guide: Your IDE Knows Everything

Everything you need is at your fingertips: The examples and patterns shown above are sufficient for understanding our SDK. Your IDE’s autocomplete is your most powerful tool.

The Universal CMD+Space Approach

Whether you’re using TypeScript, Python, VS Code, PyCharm, or any modern IDE, the approach is identical:

1. Type the method name → See all available methods
2. Open the parentheses → See all required and optional parameters
3. Press Cmd+Space (Mac) or Ctrl+Space (Windows/Linux) → Get instant documentation

This works universally because our SDKs are fully typed with comprehensive documentation.

TypeScript

// Start typing and your IDE will guide you through everything:
client.search.  // - Shows: retrieve, fullTextSearch, qna

client.search.retrieve({
  // - Cmd+Space here shows all parameters with documentation
  query: "your search query",
  tenant_id: "required-tenant-id",
  // Your IDE knows these are optional:
  max_chunks: 10,
  alpha: 0.7,
  personalise_search: true
})

Why This Approach is Complete

Our SDKs are auto-generated from the same API specification that powers this documentation, ensuring:

• 100% Parameter Coverage: Every field in the API docs appears in your IDE
• Accurate Type Information: Required vs optional, data types, validation rules
• Inline Documentation: Parameter descriptions appear as you type
• Live Examples: The @example annotations in our type definitions show real usage

The examples you’ve seen above demonstrate every pattern you’ll encounter. Once you understand the tenant/sub-tenant concept and the resource organization (client.upload.uploadText, client.search.retrieve, etc.), your IDE will handle the rest.

Resource Organization

Our SDK follows a predictable structure that mirrors the API endpoints.

Don’t overthink it: The patterns shown in our complete workflow example cover 90% of use cases. For anything else, trust your IDE’s autocomplete - it knows the exact structure and will guide you perfectly.

For in-depth explanations of each function: While your IDE’s autocomplete will guide you through the basic usage, refer to the next sections of this documentation for detailed explanations of every API endpoint, parameter options, and advanced use cases.