> ## Documentation Index > Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > RESTful HTTP API for the Kodexa Platform, covering documents, assistants, agents, knowledge, and workflow orchestration with full programmatic access.
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](/sdk/python/getting-started) and enables custom integrations. ## Base URL All API endpoints are relative to your Kodexa Platform instance: ```text theme={null} 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: ```bash theme={null} curl -X GET "https://platform.kodexa-enterprise.com/api/projects" \ -H "x-api-key: your-api-key-here" ``` **Python example:** ```python theme={null} 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: * **``** - the response shape. `required` lists the fields the server always returns, and `nullable` marks the ones that can come back as `null`. * **`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`. * **`UpdateRequest`** - the body accepted by `PUT`. Nothing is required, `changeSequence` is kept for optimistic locking (see [Update Semantics](#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 `CreateRequest` and update calls take `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: ```text theme={null} 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:** ```json theme={null} { "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](/guides/reference/filtering-api). Common operators include `==`, `!=`, `=like=`, `=in=`, `and`, and `or`. Strings must be single-quoted. ```text theme={null} GET /api/executions?filter=status=='FAILED' and assistantId=='{id}' ``` * **`query`** - Free-text search across searchable fields (typically `name` and `description`). ```text theme={null} GET /api/projects?query=invoice ``` * **`sort`** - Sort results with `field:direction` pairs. Separate multiple sorts with `;`. Direction defaults to `asc`. ```text theme={null} GET /api/executions?sort=createdOn:desc ``` See the full [Filtering API Reference](/guides/reference/filtering-api) 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:** ```json theme={null} { "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](/api-reference/projects/get-projects)** - Container for tasks, assistants, and resources * **Tasks** - Document processing and workflow tasks * **[Assistants](/api-reference/assistants/get-assistants)** - AI assistant configurations and definitions * **[Documents](/api-reference/documentfamilies/get-document-families)** - Document families and content * **[Stores](/api-reference/document-stores/get-document-stores)** - Document, data, and model storage * **[Knowledge](/api-reference/knowledge-sets/get-knowledge-sets)** - Knowledge sets, items, and features * **[Executions](/api-reference/executions/get-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: ```text theme={null} 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](/sdk/python/getting-started) which provides a high-level interface to this API: ```python theme={null} 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