Skip to main content
The Python SDK includes 959 Pydantic models 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

ModelDescription
OrganizationOrganization with members, subscriptions, and settings
ProjectProject containing assistants, stores, and taxonomies
MembershipUser membership in an organization

​
Assistants & Execution

ModelDescription
AssistantAssistant configuration within a project
AssistantDefinitionDeployable assistant definition (module-level)
ExecutionAn execution of an assistant pipeline
ExecutionEventEvents emitted during execution

​
Documents & Storage

ModelDescription
DocumentFamilyA document family in a store
StoreDocument or data store
ContentObjectA content object (KDDB, native file, etc.)

​
Knowledge System

ModelDescription
KnowledgeSetA set of knowledge items
KnowledgeItemAn individual knowledge item
KnowledgeFeatureA feature attached to knowledge items or document families
KnowledgeItemTypeType definition for knowledge items
KnowledgeFeatureTypeType definition for knowledge features

​
Tasks & Workflow

ModelDescription
TaskA workflow task
TaskTemplateTemplate for creating tasks
TaskActivityActivity log entry for a task
TaskDocumentFamilyAssociation between a task and a document family

​
Users & Access

ModelDescription
UserPlatform user
PlatformOverviewPlatform configuration and version info

​
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

MethodDescription
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

MethodDescription
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:000.000Z). This matches the Java/Go API format.