Skip to main content

​
Welcome to the Kortix API

The Kortix API provides a RESTful interface for building AI-powered applications. Access agent execution, thread management, file uploads, and more through a unified API.

​
Base URLs

Kortix provides different base URLs depending on your environment: 
https://api.kortix.com/v1
All API requests must be made to the /v1 prefix. For example: 
curl https://api.kortix.com/v1/health

​
API Architecture

The Kortix API is built with:
  • FastAPI Framework: High-performance async Python API
  • PostgreSQL Database: Powered by Supabase with real-time capabilities
  • Redis Caching: For authentication, rate limiting, and performance optimization
  • CloudWatch Metrics: System monitoring and logging (production)

​
Key Features

  • Multi-tenancy: Account-based resource isolation
  • Real-time Streaming: Server-Sent Events (SSE) for agent runs
  • File Uploads: Support for multiple file types with validation
  • Webhook Integration: Trigger-based automation
  • Sandbox Execution: Isolated code execution environments

​
Rate Limits

The API implements several rate limiting mechanisms to ensure fair usage:

​
Concurrent Request Limits

​
max_concurrent_ips
integer
default:"25"
Maximum concurrent IP addresses allowed per instance
Source: api.py:69 
MAX_CONCURRENT_IPS = 25

​
API Key Usage Throttling

API key last_used_at timestamps are throttled to reduce database load:
​
API_KEY_LAST_USED_THROTTLE_SECONDS
integer
default:"900"
Minimum seconds between last_used_at updates (default: 15 minutes)
Source: core/services/api_keys.py:447-448

​
Billing-Based Limits

Rate limits vary by subscription tier:
  • Free Tier: Limited concurrent runs
  • Paid Tiers: Higher concurrency and priority execution
  • Enterprise: Custom limits
Limits are enforced at the account level and checked before agent execution.

​
Request Format

All requests must include proper authentication headers: 
curl https://api.kortix.com/v1/agents \
  -H "X-API-Key: pk_xxxxx:sk_xxxxx"

​
Content Types

The API accepts and returns JSON by default: 
Content-Type: application/json
Accept: application/json
For file uploads, use multipart/form-data: 
Content-Type: multipart/form-data

​
Response Format

All responses follow a consistent structure:
​
status
string
HTTP status indicator (e.g., “ok”, “error”)
​
data
object
Response payload containing requested data
​
timestamp
string
ISO 8601 timestamp of the response

​
Success Response Example

{
  "status": "ok",
  "timestamp": "2026-03-02T10:30:00.000Z",
  "instance_id": "worker-abc123"
}
See Errors for error response format.

​
Health Check

Monitor API health and status: 
curl https://api.kortix.com/v1/health

​
Health Response

{
  "status": "ok",
  "timestamp": "2026-03-02T10:30:00.000Z",
  "instance_id": "i-abc123xyz"
}
Source: api.py:444-465

​
Graceful Shutdown

During deployment, the health check returns 503 when shutting down: 
{
  "status": "shutting_down",
  "timestamp": "2026-03-02T10:30:00.000Z",
  "instance_id": "i-abc123xyz"
}
This ensures Kubernetes stops routing traffic before terminating the pod. Source: api.py:450-459

​
System Metrics

Access real-time system metrics: 
curl https://api.kortix.com/v1/metrics
​
active_agent_runs
integer
Total active agent runs across all instances
​
active_redis_streams
integer
Number of active Redis stream keys
​
orphaned_streams
integer
Streams without database records (should be 0)
Source: api.py:480-496

​
CORS Configuration

The API supports cross-origin requests from:
  • https://www.kortix.com
  • https://kortix.com
  • https://dev.kortix.com
  • https://staging.kortix.com
  • https://*.kortix.com (all subdomains)
  • https://*-kortixai.vercel.app (Vercel preview deployments)
  • http://localhost:3000 (local development)
Source: api.py:331-358

​
Allowed Methods

GET, POST, PUT, PATCH, DELETE, OPTIONS

​
Allowed Headers

Content-Type, Authorization, X-Project-Id, X-MCP-URL, 
X-MCP-Type, X-MCP-Headers, X-API-Key

​
Next Steps

Authentication

Learn how to authenticate with API keys and JWT tokens

Error Handling

Understand error responses and status codes

Build docs developers (and LLMs) love

Get started for freeTalk to us