API Introduction

Overview of the Kortix API, base URLs, versioning, and rate limits

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:

Production

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:

API Key

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:

Standard Health Check

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