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-enterprise.com/api
For Enterprise deployments, replace with your instance URL.

​
Authentication

​
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-enterprise.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-enterprise.com/api/projects",
    headers=headers
)

​
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
}

​
Filtering & Sorting

Most list endpoints support filter, query, and sort query parameters to narrow and order results.
  • filter - Filter results using Kodexa filter syntax. Uses : for equals, ~ for like/contains, and/or to combine conditions. Strings must be single-quoted. 
    GET /api/executions?filter=status: 'FAILED' and assistantId: '{id}'
  • query - Free-text search across searchable fields (typically name and description). 
    GET /api/projects?query=invoice
  • sort - Sort results by field name, with optional direction (asc or desc). 
    GET /api/executions?sort=createdOn,desc
See the full Filtering API Reference for all operators and examples.

​
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-enterprise.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