Platform Models

Auto-generated Pydantic models for the Kodexa Platform API providing type-safe access to all platform resources from the Python SDK.

The Python SDK includes 489 Pydantic models and 29 enumeration classes auto-generated from the Kodexa API OpenAPI specification using datamodel-codegen. These models provide full type safety when working with the platform API.

How They’re Generated

The models in kodexa_document.model._generated are produced by running datamodel-codegen against the api-docs.yaml OpenAPI specification from kodexa-api. This happens as part of the CI pipeline and ensures the Python models always match the API.

Importing Models

# Import specific models from the generated module
from kodexa_document.model._generated import (
    Organization,
    Project,
    Task,
    DocumentFamily,
    Assistant,
    Execution,
    User,
    Store,
)

Key Model Categories

Organizations & Projects

Model	Description
Organization	Organization with members, subscriptions, and settings
Project	Project containing assistants, stores, and taxonomies
Membership	User membership in an organization

Assistants & Execution

Model	Description
Assistant	Assistant configuration within a project
AssistantDefinition	Deployable assistant definition (module-level)
Execution	An execution of an assistant pipeline
ExecutionEvent	Events emitted during execution

Documents & Storage

Model	Description
DocumentFamily	A document family in a store
Store	Document or data store
ContentObject	A content object (KDDB, native file, etc.)

Knowledge System

Model	Description
KnowledgeSet	A set of knowledge items
KnowledgeItem	An individual knowledge item
KnowledgeFeature	A feature attached to knowledge items or document families
KnowledgeItemType	Type definition for knowledge items
KnowledgeFeatureType	Type definition for knowledge features

Tasks & Workflow

Model	Description
Task	A workflow task; carries status_slug rather than an embedded status
TaskStatus	An organization’s task status (label, color, status_type)
TaskTemplate	Template for creating tasks
TaskActivity	Activity log entry for a task
TaskDocumentFamily	Association between a task and a document family, positioned by ordinal
ActivityDocumentFamily	Association between an activity and a document family, positioned by ordinal

Users & Access

Model	Description
User	Platform user
PlatformOverview	Platform configuration and version info

Request Models

Alongside the response model for each resource, the generated module contains a <Entity>CreateRequest and an <Entity>UpdateRequest, so a create or update payload can be built from a model that holds only the fields the server accepts:

• <Entity> — the response shape, everything the API returns.
• <Entity>CreateRequest — for POST bodies. Server-generated fields (id, uuid, createdOn, updatedOn, changeSequence) are absent, so they cannot be sent by accident.
• <Entity>UpdateRequest — for PUT bodies. Keeps changeSequence for optimistic locking and omits the ownership fields an update never writes (for example projectId on a task).

from kodexa_document.model._generated import (
    TaskCreateRequest,
    TaskUpdateRequest,
)

# Create payload — no server-generated fields to leave blank
new_task = TaskCreateRequest(
    projectId="a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    title="Review Q4 invoices",
    statusSlug="in-review",
)

# Update payload — carries the change sequence you read back
change = TaskUpdateRequest(
    title="Review Q4 invoices (revised)",
    changeSequence=7,
)

Which fields the server requires is described by the API specification served at GET /v3/api-docs; the generated Python models leave every field optional so that partial payloads remain expressible.

Enumerations

Enumeration classes take their names from the API specification rather than from generator-invented ones, so each enum has one stable name across every generated client. They are StrEnum subclasses, so a member compares equal to its wire string.

from kodexa_document.model import ExecutionStatus
from kodexa_document.model._generated import TaskStatusType

TaskStatusType.OPEN == "OPEN"  # True

Enumeration	Covers
ExecutionStatus	Execution lifecycle state
ExecutionStatusMessageType	Type of an execution status message
TaskStatusType	OPEN, IN_PROGRESS, DONE, BLOCKED, PENDING
TaskActivityType	Kind of task activity entry
TaskSignalOutcome	Reviewer signal outcome
SortDirection	Sort order on list endpoints
AuditAction	Action recorded in an audit entry
DocumentActorType	Who acted on a document
TaxonCardinality / TaxonValuePath / TaxonMetadataValue	Taxon configuration
AnalyticsFieldType / AnalyticsMetricType	Analytics dataset field and metric types
WebLlmModelSize	Model size for browser-side models
SessionState	Session lifecycle state
PipelineStepType	Kind of pipeline step
ChatMessageRole	Author role on a chat message

Renamed enumerations

If you import enum classes by their old generated names, update the imports:

Previous name	Current name
Status	ExecutionStatus
StatusType4	TaskStatusType
Type6	TaskActivityType
Direction	SortDirection
Action	AuditAction
ActorType	DocumentActorType
Cardinality	TaxonCardinality
ValuePath	TaxonValuePath
MetadataValue	TaxonMetadataValue
AnalyticsDatasetFieldType	AnalyticsFieldType
ModelType	WebLlmModelSize
Outcome	TaskSignalOutcome
State	SessionState
StepType	PipelineStepType

ExecutionStatus is also exported from the top level, so from kodexa_document.model import ExecutionStatus works. The values on the wire are unchanged — only the Python type names are.

Task Status

Task carries the status as status_slug only. Resolve the label, color and status_type through the organization’s task statuses:

from kodexa_document.model._generated import TaskStatus

task = client.tasks.get("task-id-123")

response = client.get(
    "/api/task-statuses",
    params={"filter": f"organization.id:'{organization_id}'", "pageSize": 100},
)
statuses = {s["slug"]: TaskStatus(**s) for s in response.json()["content"]}

status = statuses.get(task.status_slug)
if status:
    print(status.label, status.color, status.status_type)

To move a task to another status, pass the TaskStatus to the task endpoint’s update_status(), which sends the slug for you.

KodexaBaseModel

All generated models inherit from KodexaBaseModel, which extends Pydantic’s BaseModel with:

camelCase / snake_case Support

Models accept both camelCase (matching the JSON API) and snake_case (Pythonic) field names:

from kodexa_document.model._generated import Organization

# Both work - populate_by_name=True
org = Organization(name="Acme Corp", slug="acme")
org = Organization(**{"name": "Acme Corp", "slug": "acme"})

# API response with camelCase also works
org = Organization(**{
    "name": "Acme Corp",
    "organizationType": "BUSINESS"
})

Dict-like Access

Models support dict-style bracket access and get():

org = Organization(name="Acme Corp")

# Dict-like access
name = org["name"]
org["name"] = "New Name"

# Safe get with default
value = org.get("missing_field", "default")

# Containment check
if "name" in org:
    print(org["name"])

Extra Fields

The extra='allow' configuration means models accept fields not in the schema without raising errors. This handles forward-compatibility when the API adds new fields.

Taxonomy and Taxon Extensions

The SDK extends the generated TaxonomyBase and TaxonBase models with navigation methods. These are imported from the top-level package, not from _generated:

from kodexa_document import Taxonomy

taxonomy_data = {
    "name": "Invoice",
    "slug": "invoice",
    "taxons": [
        {
            "name": "Header",
            "taxonType": "GROUP",
            "children": [
                {"name": "Invoice Number", "taxonType": "STRING"},
                {"name": "Date", "taxonType": "DATE"},
                {"name": "Total", "taxonType": "DECIMAL"}
            ]
        }
    ]
}

taxonomy = Taxonomy(**taxonomy_data)
taxonomy.update_paths()

# Find a taxon by path
total = taxonomy.get_taxon_by_path("/Header/Total")
print(total.name)  # "Total"

# Get all group taxons
groups = taxonomy.taxons[0].groups()

# Navigate with path parts
date = taxonomy.taxons[0].find_taxon("Date")

Taxon Methods

Method	Description
update_path(parent_path)	Recursively sets path on this taxon and its children
find_taxon(*path_parts)	Search children by name at each level
get_taxon_by_path(path)	Find a taxon matching the exact path string
groups()	Return all group-type taxons at this level and below
get_simplified_structure()	Return a minimal dict representation

Taxonomy Methods

Method	Description
get_taxon_by_path(path)	Search all root taxons and children by path
update_paths()	Call update_path() on every root taxon
build_guidance_tags()	Build {path: [examples]} dict for guidance

Deserializing API Responses

The models integrate naturally with API response data:

import requests
from kodexa_document.model._generated import Project

# Fetch from API
response = requests.get(
    "https://platform.kodexa.ai/api/projects/abc-123",
    headers={"X-API-Key": "your-token"}
)

# Deserialize into typed model
project = Project(**response.json())
print(project.name)
print(project.slug)

For the full platform client experience with pagination, authentication, and endpoint helpers, see the Platform Client page.

DateTime Handling

KodexaBaseModel uses a custom StandardDateTime type that serializes datetimes to millisecond-precision ISO 8601 strings with Z suffix (e.g., 2026-01-15T10:30:00.000Z). This matches the Java/Go API format.