API Reference

RESTful HTTP API for the Kodexa Platform, covering documents, assistants, agents, knowledge, and workflow orchestration with full programmatic access.

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
)

OpenAPI Specification

The machine-readable specification for this API is served by your instance at GET /v3/api-docs, using the same authentication as any other endpoint. Use it to generate typed clients; the endpoint reference on this site is generated from it and has been refreshed to the 2026.10 contract.

Request and Response Schemas

Each resource is described by three schemas rather than one:

• <Entity> - the response shape. required lists the fields the server always returns, and nullable marks the ones that can come back as null.
• <Entity>CreateRequest - the body accepted by POST. Server-generated fields (id, uuid, createdOn, updatedOn, changeSequence) are removed, and required names only what the server insists on - TaskCreateRequest, for example, requires just projectId.
• <Entity>UpdateRequest - the body accepted by PUT. Nothing is required, changeSequence is kept for optimistic locking (see Update Semantics), and the ownership fields an update never writes are omitted.

A nullable reference to another object is expressed as allOf plus nullable: true, so a generated type carries both the target schema and the fact that the field can be null. Fields that hold free-form JSON - workspace storage, prompt metadata, platform-event payloads - are described as JSON values (object, array, or scalar) rather than base64-encoded strings.

Named Enumerations

Every enumeration is emitted as a named component and referenced by $ref: TaskStatusType, ExecutionStatus, ExecutionStatusMessageType, SortDirection, AuditAction, ChatMessageRole, WebLlmModelSize, and the rest. Generators therefore produce one stable type per enumeration instead of inventing names such as Type1 or StatusType3.

TaskStatusType is OPEN | IN_PROGRESS | DONE | BLOCKED | PENDING. The older project-scoped task status type (TODO / IN_PROGRESS / DONE) is retired; a project template that still declares a task status with statusType: TODO is accepted and stored as OPEN.

Operation IDs

Operation IDs are unique, so no operation is dropped from a generated client by a name collision:

• PUT /api/tasks/{id}/status is setTaskStatus, which leaves updateTaskStatus to PUT /api/task-statuses/{id}.
• GET /api/task-groups/{id}/history is listHistoryForTaskGroup, which leaves listTaskGroupHistory to GET /api/task-group-history.
• cancelExecution is defined once, on PUT /api/executions/{executionId}/cancel.

Changed in 2026.10: the request and response JSON on the wire is unchanged - only the specification and the clients generated from it change. If you generate a client, regenerate it against a 2026.10 instance and expect compile-time changes: create calls take <Entity>CreateRequest and update calls take <Entity>UpdateRequest instead of the response type; response fields that were all optional are now typed as required where the server always sends them; enum types take their component names; JSON-blob fields become objects instead of strings; and the two operations above are renamed (updateTaskStatus and listTaskGroupHistory now refer to the task-status and task-group-history endpoints). Hand-written HTTP integrations need no change.

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