Skip to main content

​
Overview

The Kodexa Platform API provides programmatic access to all platform capabilities including document processing, AI assistants, knowledge management, and workflow orchestration. This REST API is the foundation that powers the Kodexa Python SDK and enables custom integrations.

​
Base URL

All API endpoints are relative to your Kodexa Platform instance: 
https://platform.kodexa.com/api
For Enterprise deployments, replace with your instance URL.

​
Authentication

API Authentication Migration in ProgressWe are migrating from the legacy x-access-token header to the new x-api-key header for API authentication.Current behavior:
  • Preferred: Use x-api-key header with your API key
  • Deprecated: x-access-token header still works but will be removed in a future release
  • If both headers are provided, x-api-key takes precedence and x-access-token is ignored
Migration timeline:
  • Please update all integrations to use x-api-key as soon as possible
  • The legacy x-access-token header may be disabled in future releases
See the authentication examples below for the correct usage.

​
Getting Your API Key

  1. Log in to the Kodexa Platform
  2. Navigate to your profile settings
  3. Go to the API Keys section
  4. Generate a new API key or copy an existing one

​
Using Your API Key

Include your API key in the x-api-key header with every request: 
curl -X GET "https://platform.kodexa.com/api/projects" \
  -H "x-api-key: your-api-key-here"
Python example: 
import requests

headers = {
    "x-api-key": "your-api-key-here",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://platform.kodexa.com/api/projects",
    headers=headers
)
Legacy authentication (deprecated): 
# Don't use this - migrate to x-api-key
curl -X GET "https://platform.kodexa.com/api/projects" \
  -H "x-access-token: your-token-here"

​
API Conventions

​
Resource Patterns

The Kodexa API follows RESTful conventions:
  • List resources: GET /api/{resource} - Returns paginated list
  • Get single resource: GET /api/{resource}/{id} - Returns specific resource
  • Create resource: POST /api/{resource} - Creates new resource
  • Update resource: PUT /api/{resource}/{id} - Updates existing resource
  • Delete resource: DELETE /api/{resource}/{id} - Deletes resource

​
Pagination

List endpoints support pagination via query parameters: 
GET /api/tasks?page=0&pageSize=20
Parameters:
  • page (integer, optional) - Zero-indexed page number (default: 0)
  • pageSize (integer, optional) - Items per page (default: 10, max: 100)
Response structure: 
{
  "content": [...],
  "totalPages": 5,
  "totalElements": 47,
  "number": 0,
  "size": 10,
  "first": true,
  "last": false
}

​
Error Responses

The API uses standard HTTP status codes:
  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid API key
  • 403 Forbidden - Authenticated but not authorized
  • 404 Not Found - Resource doesn’t exist
  • 500 Internal Server Error - Server error
Error response format: 
{
  "error": "Resource not found",
  "message": "Task with ID 'abc123' does not exist",
  "status": 404
}

​
Common Resources

The API is organized around these core resource types:
  • Projects - Container for tasks, assistants, and resources
  • Tasks - Document processing and workflow tasks
  • Assistants - AI assistant configurations and definitions
  • Documents - Document families and content
  • Stores - Document, data, and model storage
  • Knowledge - Knowledge sets, items, and features
  • Executions - Pipeline and process execution tracking

​
Rate Limiting

API requests are subject to rate limiting to ensure platform stability:
  • Rate limit: 100 requests per minute per API key
  • Burst limit: 20 requests per second
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1634567890
When rate limited, you’ll receive a 429 Too Many Requests response.

​
Using the Python SDK

For Python developers, we recommend using the Kodexa Python SDK which provides a high-level interface to this API: 
from kodexa import KodexaPlatform

# Initialize with API key
platform = KodexaPlatform(
    url="https://platform.kodexa.com",
    api_key="your-api-key-here"
)

# Work with resources naturally
project = platform.get_project("my-project")
tasks = project.get_tasks()
The SDK handles authentication, pagination, error handling, and provides typed models for all resources.

​
API Endpoints

Browse the complete API endpoint documentation in the Endpoints section below. Each endpoint includes:
  • HTTP methods and paths
  • Request/response schemas
  • Required and optional parameters
  • Example requests and responses
  • Authentication requirements