Intakes

Intakes provide automated document ingestion endpoints. Each intake defines a way for external systems to submit documents into a specific document store, triggering processing pipelines automatically.

Intakes page showing configured intake endpoints with names, target stores, and status

How Intakes Work

An intake creates an HTTP endpoint that external systems can send documents to. When a document arrives at an intake endpoint:

The document is uploaded to the configured document store
If a script is configured, it runs to validate or enrich the document metadata
A document family is created for tracking
If a task template is configured, a task is automatically created
Any configured knowledge features are assigned to the document
Domain events are published, triggering any subscribed processing pipelines

Upload Endpoint

Each intake exposes an upload endpoint at:

POST /api/intake/{orgSlug}/{intakeSlug}

For example, an intake with slug invoice-upload in organization acme-corp would be available at:

POST /api/intake/acme-corp/invoice-upload

Single File Upload

curl -X POST https://platform.kodexa.ai/api/intake/acme-corp/invoice-upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@invoice.pdf" \
  -F 'metadata={"vendor": "Acme Inc", "department": "finance"}'

Multiple File Upload

When Allow Multiple Files is enabled on the intake, you can upload multiple files in a single request:

curl -X POST https://platform.kodexa.ai/api/intake/acme-corp/invoice-upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@invoice1.pdf" \
  -F "file=@invoice2.pdf" \
  -F 'metadata=[{"vendor": "Acme"}, {"vendor": "Globex"}]'

When providing metadata for multiple files, use a JSON array where each element corresponds to a file by index. If a single JSON object is provided instead, it is applied to all files.

Request Parameters

Parameter	Type	Required	Description
`file`	multipart file	Yes	One or more files to upload
`path`	string	No	Document path in the store (defaults to filename)
`metadata`	JSON	No	Key-value metadata to attach to the document
`documentVersion`	string	No	Version identifier stored on the content object
`externalData`	JSON	No	External data JSON object injected into the KDDB document under key `"default"`. Accessible via `doc.get_external_data()` in processing modules.
`labels`	string	No	Comma-separated label names to assign (normalized to uppercase, created if new)
`statusId`	string	No	Document status ID to set on the document family
`knowledgeFeatures`	JSON	No	Array of `{"id": "..."}` objects — merged with intake-configured features

Response

Returns HTTP 201 on success with the created document family object. For multiple files, returns an array of document family objects.

External data is stored directly in the KDDB document, not in a separate database table. Processing modules can access it via doc.get_external_data() (Python) or doc.getExternalData() (TypeScript/WASM). The platform UI reads it directly from the loaded document.

Configuring an Intake

Create Intake

Click the add button on the Intakes page. Provide a name and slug for the intake. The slug determines the upload endpoint URL.

Select Target Store

Choose the document store where incoming documents should be stored.

Configure Options

Set up optional features such as scripting, task templates, knowledge features, and metadata.

Intake Settings

Setting	Description
Name	Human-readable label for the intake
Slug	URL-safe identifier used in the upload endpoint path
Description	Optional description of the intake’s purpose
Active	When disabled, the intake rejects all uploads
Allow Multiple Files	Enable uploading multiple files in a single request
Target Store	The document store where uploaded files are saved

Script Tab

Intakes support a JavaScript scripting tab that lets you run custom logic on each uploaded file before it is stored. Scripts run in a Goja JavaScript runtime with a 5-second timeout.

Available Variables

Variable	Type	Description
`filename`	string	Original uploaded filename
`fileSize`	number	File size in bytes
`mimeType`	string	Detected MIME type
`metadata`	object	Mutable metadata object (merged from intake config + upload params)
`document.text`	string	Extracted text content (first 5 pages for PDFs)
`document.pageCount`	number	Page count if available
`document.metadata`	object	Document-level metadata
`log(level, message)`	function	Write to server logs (`debug`, `info`, `warn`, `error`)

Return Value

Scripts return an object that controls how the upload is processed:

({
  metadata: metadata,       // Modified metadata object
  reject: false,            // Set true to reject the upload
  rejectReason: "",         // Reason string shown to the caller
  taskTemplates: [          // Optional: control which tasks are created
    {
      slug: "template-slug",    // Task template slug (required)
      priority: 1,              // Override task priority
      teamSlug: "team-slug",    // Override team assignment
      assigneeEmail: "a@b.com", // Override assignee
      title: "Custom title",    // Override task title
      description: "...",       // Override task description
      metadata: {}              // Per-task metadata
    }
  ]
})

Field	Type	Required	Description
`metadata`	object	No	Modified metadata — replaces the merged metadata for this document
`reject`	boolean	No	Set `true` to reject the upload (returns HTTP 400)
`rejectReason`	string	No	Reason shown to the caller when rejected
`taskTemplates`	array	No	Task templates to create for this document (see below)

Task Templates Array

When the taskTemplates field is present in the return value, the script takes full control of task creation:

Array with entries — creates one task per entry, resolving each template by slug
Empty array [] — creates no tasks, even if a static template is configured on the intake
Field omitted entirely — falls back to the static task template configured on the intake (backward compatible)

Each entry in the array supports these fields:

Field	Type	Required	Description
`slug`	string	Yes	The slug of the task template to use. Must exist in the same organization.
`priority`	number	No	Override the task priority (0 = default)
`teamSlug`	string	No	Override team assignment by team slug
`assigneeEmail`	string	No	Override assignee by email address
`title`	string	No	Override the task title (defaults to filename or AI naming)
`description`	string	No	Override the task description
`metadata`	object	No	Metadata object stored on the created task

When scripting is enabled, the static Task Template dropdown in the Settings tab is disabled. All task creation logic moves to the script.

Example: Validate File Size

if (fileSize > 50 * 1024 * 1024) {
  return {
    metadata: metadata,
    reject: true,
    rejectReason: "File exceeds 50MB limit"
  };
}

// Enrich metadata with detected info
metadata["source"] = "intake";
metadata["originalFilename"] = filename;

return {
  metadata: metadata,
  reject: false,
  rejectReason: ""
};

Example: Route by Document Content

log("info", "Processing: " + filename);

if (document.text.includes("CONFIDENTIAL")) {
  metadata["classification"] = "confidential";
  metadata["requiresReview"] = "true";
}

return {
  metadata: metadata,
  reject: false,
  rejectReason: ""
};

Example: Dynamic Task Routing

Route documents to different task templates with custom overrides based on content:

log("info", "Classifying: " + filename);

var templates = [];

if (document.text.indexOf("INVOICE") >= 0) {
  templates.push({
    slug: "invoice-review",
    priority: 2,
    teamSlug: "finance-team",
    title: "Invoice Review: " + filename
  });

  // High-value invoices also get an approval task
  var amount = document.text.match(/\$[\d,]+\.?\d*/);
  if (amount) {
    templates.push({
      slug: "invoice-approval",
      priority: 1,
      title: "Approve: " + filename + " (" + amount[0] + ")",
      metadata: { detectedAmount: amount[0] }
    });
  }
} else if (document.text.indexOf("CONTRACT") >= 0) {
  templates.push({
    slug: "legal-review",
    teamSlug: "legal-team",
    title: "Contract Review: " + filename
  });
} else {
  log("info", "No matching template for: " + filename);
}

({
  metadata: metadata,
  reject: false,
  taskTemplates: templates
})

This script inspects the document text and:

Creates an invoice review task for invoices, plus an approval task for invoices with dollar amounts
Creates a legal review task for contracts
Skips task creation entirely for unrecognized documents

Enable the Script toggle to activate script execution. You can disable it without deleting the script code.

Loading Shared Modules

Intake scripts can load shared JavaScript modules using the Module Refs picker in the Script tab. Pre-loaded modules’ functions and variables are available in global scope within your intake script, letting you reuse common validation, transformation, or enrichment logic across multiple intakes. Select one or more JavaScript modules from your organization. They are fetched and executed in order before your intake script runs.

// Assuming "my-org/validation-helpers" is loaded via Module Refs
if (!validateFileType(mimeType)) {
  return { metadata: metadata, reject: true, rejectReason: "Unsupported file type" };
}

metadata["normalized_name"] = cleanFilename(filename);
return { metadata: metadata, reject: false, rejectReason: "" };

Task Template

Static Assignment

Select a task template from the dropdown to automatically create a task for each uploaded document. When configured:

A task is created using the selected template
The task title defaults to the uploaded filename
The uploaded document is linked to the task
If the template has AI naming configured, the task title is generated from the document content

This is useful for simple intake workflows where every document needs the same type of task.

Script-Driven Assignment

When a processing script is enabled on the intake, the static task template dropdown is disabled. Instead, the script controls which tasks are created by returning a taskTemplates array in its return value. This allows:

Conditional routing — different document types create different tasks
Multiple tasks — a single document can create several tasks across different templates
No tasks — some documents may not need a task at all
Per-task overrides — customize priority, team, assignee, title, and metadata per task

See the Script Tab section for the full return value reference and examples.

Task template slugs in the script must match existing templates in your organization. If a slug cannot be resolved, that template is skipped and a warning is logged. The remaining templates continue to be created.

Knowledge Features

Select one or more knowledge feature types to automatically assign to every document uploaded through this intake. This lets you pre-classify documents at ingestion time — for example, tagging all documents from a specific intake as belonging to a particular vendor or document category.

Processing Metadata

The Processing Metadata section lets you define key-value pairs that are attached to every document uploaded through this intake. These metadata values are available to downstream processing modules and assistants. Metadata is merged in this order (later values override earlier ones):

Intake-level metadata (configured here)
Metadata extracted from the document file
Per-upload metadata (provided in the API request)
Script modifications (if a script is enabled)

The following keys are reserved and automatically stripped from the metadata object before storage. Use them as separate form parameters instead: externalData, labels, statusId, knowledgeFeatures, documentVersion.

Labels are normalized to uppercase before storage. For example, labels=invoice,urgent creates labels INVOICE and URGENT. Labels that don’t exist in the organization are created automatically.

API Tokens

The API Tokens tab lets you create scoped tokens for machine-to-machine authentication against a specific intake endpoint. Unlike user API keys, intake tokens are scoped to a single intake and bypass user authentication — making them ideal for automated pipelines, third-party integrations, and CI/CD workflows.

Creating a Token

Open the API Tokens tab

Select an intake and navigate to the API Tokens tab.

Create a new token

Click the add button. Optionally set an expiration date.

Copy the token

The plaintext token (prefixed with kit_) is shown only once. Copy it immediately and store it securely.

Token values are shown only at creation time. After you close the dialog, only a hint (last 4 characters) is displayed. If you lose the token, you must create a new one.

Using Intake Tokens

Pass the token in the Authorization header when uploading to the intake endpoint:

curl -X POST https://platform.kodexa.ai/api/intake/acme-corp/invoice-upload \
  -H "Authorization: Bearer kit_abc123..." \
  -F "file=@invoice.pdf"

Intake tokens only grant access to the specific intake they were created for. They cannot be used to access other API endpoints.

Managing Tokens

The API Tokens tab displays all tokens for the intake with their creation date, hint, and expiration status. Click the delete button to revoke a token. A confirmation dialog is shown before deletion.

Token Security

Tokens are hashed with SHA-256 before storage — the platform never stores plaintext tokens
Each token is scoped to a single intake and cannot access other resources
Tokens can have optional expiration dates
Revoked tokens take effect immediately

Each intake provides a unique URL. Keep intake URLs and authentication credentials secure, as anyone with access can submit documents to your organization.

Introduction

Organization Home

Projects

Project Home

Workspace

How Intakes Work

Upload Endpoint

Single File Upload

Multiple File Upload

Request Parameters

Response

Configuring an Intake

Intake Settings

Script Tab

Available Variables

Return Value

Task Templates Array

Example: Validate File Size

Example: Route by Document Content

Example: Dynamic Task Routing

Loading Shared Modules

Task Template

Static Assignment

Script-Driven Assignment

Knowledge Features

Processing Metadata

API Tokens

Creating a Token

Using Intake Tokens

Managing Tokens

Token Security

Introduction

Organization Home

Projects

Project Home

Workspace

​How Intakes Work

​Upload Endpoint

​Single File Upload

​Multiple File Upload

​Request Parameters

​Response

​Configuring an Intake

​Intake Settings

​Script Tab

​Available Variables

​Return Value

​Task Templates Array

​Example: Validate File Size

​Example: Route by Document Content

​Example: Dynamic Task Routing

​Loading Shared Modules

​Task Template

​Static Assignment

​Script-Driven Assignment

​Knowledge Features

​Processing Metadata

​API Tokens

​Creating a Token

​Using Intake Tokens

​Managing Tokens

​Token Security

How Intakes Work

Upload Endpoint

Single File Upload

Multiple File Upload

Request Parameters

Response

Configuring an Intake

Intake Settings

Script Tab

Available Variables

Return Value

Task Templates Array

Example: Validate File Size

Example: Route by Document Content

Example: Dynamic Task Routing

Loading Shared Modules

Task Template

Static Assignment

Script-Driven Assignment

Knowledge Features

Processing Metadata

API Tokens

Creating a Token

Using Intake Tokens

Managing Tokens

Token Security