API Reference - Kodexa Developer Portal

Kodexa API reference with authenticated requests, endpoints, and platform resources

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

Log in to the Kodexa Platform
Navigate to your profile settings
Go to the API Keys section
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

Update Semantics

Create and update requests persist exactly the fields you send:

Explicit values always persist - sending false or 0 writes false or 0, including on fields that have a server-side default
Omitted fields stay unchanged - leave a field out of the body to leave its stored value untouched, so sparse updates are reliable
null clears - sending null clears a nullable field
Round-trips are safe - echoing back the body of a GET as a PUT is a no-op

System-managed and ownership fields - id, uuid, createdOn, createdByUserId, organizationId, projectId, and soft-delete state - are ignored if included in an update body. changeSequence is never written directly; it serves only as the optimistic-locking token. Locking is enforced whenever the body carries a non-null changeSequence - including 0 on a resource that has never been updated - and a stale value returns 409 Conflict with the current sequence so you can re-fetch and retry. Omit the field (or send null) to opt out of locking. Malformed writes are rejected up front: a body that is not a JSON object, or that repeats the same field under case-variant keys (for example name and Name), returns 400 Bad Request. Uniqueness violations return 409 Conflict, and setting a non-nullable field to null or referencing a record that doesn’t exist returns 400 Bad Request. Changed in 2026.9: previously, a field set to false or 0 in an update body could be silently dropped - the request returned 200 OK but the value never changed - and on create a server-side default could overwrite an explicit false or 0. Explicit values now always persist; to leave a field unchanged, omit it from the body.

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 the SpringFilter-style syntax. Common operators include ==, !=, =like=, =in=, and, and or. 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 with field:direction pairs. Separate multiple sorts with ;. Direction defaults to asc.
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