API docs by Redocly

Kiln AI API (1.0.0)

Download OpenAPI specification:

This API is used to interact with all aspects of Kiln AI. For example, it can create and manage the data model (projects, tasks, prompts, evals, etc). It can also control the execution of the application including running tasks, evals, and more.

Settings & Utilities

Ping Server

Ping the server to check connectivity.

Responses

Response samples

Content type
application/json
null

Projects

List Projects

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Project

Request Body schema: application/json
required
v
integer (V)
Default: 1

Schema version for migration support.

Id (string) or Id (null) (Id)

Unique identifier for this record.

Path (string) or Path (null) (Path)

File system path where the record is stored.

created_at
string <date-time> (Created At)

Timestamp when the model was created. Timezone-aware; stores the writer's local offset.

created_by
string (Created By)

User ID of the creator.

name
required
string (Name) [ 1 .. 120 ] characters

The name of the project.

Description (string) or Description (null) (Description)

A description of the project for you and your team. Will not be used in prompts/training/validation.

Responses

Request samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "model_type": "string"
}

Update Project

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "model_type": "string"
}

Get Project

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "model_type": "string"
}

Import Project

query Parameters
project_path
required
string (Project Path)

File path to the project.kiln file to import.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "model_type": "string"
}

Tasks

Create Task

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "instruction": "string",
  • "requirements": [ ],
  • "output_json_schema": "string",
  • "input_json_schema": "string",
  • "thinking_instruction": "string",
  • "default_run_config_id": "string",
  • "model_type": "string"
}

List Tasks

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Task

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "instruction": "string",
  • "requirements": [ ],
  • "output_json_schema": "string",
  • "input_json_schema": "string",
  • "thinking_instruction": "string",
  • "default_run_config_id": "string",
  • "model_type": "string"
}

Delete Task

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
null

Get Task

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "instruction": "string",
  • "requirements": [ ],
  • "output_json_schema": "string",
  • "input_json_schema": "string",
  • "thinking_instruction": "string",
  • "default_run_config_id": "string",
  • "model_type": "string"
}

Get Rating Options

Determines which rating options should be shown for a given dataset item.

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
{
  • "options": [
    ]
}

Task Summaries (agent-tuned)

Return a workspace-wide list of projects and their tasks, with truncated task.instruction values. Unlike typical list endpoints, entries here are intentionally lossy — the shape is tuned for LLM-agent context efficiency, not for driving UIs that need the full Task model.

Responses

Response samples

Content type
application/json
{
  • "projects": [
    ]
}

Prompts

Create Prompt

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
Generator Id (string) or Generator Id (null) (Generator Id)

The generator ID if this prompt was auto-generated.

name
required
string (Name)

The name of the prompt.

Description (string) or Description (null) (Description)

A description of the prompt.

prompt
required
string (Prompt)

The prompt text.

Chain Of Thought Instructions (string) or Chain Of Thought Instructions (null) (Chain Of Thought Instructions)

Chain of thought instructions to include in the prompt.

Responses

Request samples

Content type
application/json
{
  • "generator_id": "string",
  • "name": "string",
  • "description": "string",
  • "prompt": "string",
  • "chain_of_thought_instructions": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "generator_id": "string",
  • "prompt": "string",
  • "chain_of_thought_instructions": "string",
  • "id": "string",
  • "type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string"
}

List Prompts

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
{
  • "generators": [
    ],
  • "prompts": [
    ]
}

Update Prompt

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

prompt_id
required
string (Prompt Id)

The unique identifier of the prompt.

Request Body schema: application/json
required
name
required
string (Name)

The updated name.

Description (string) or Description (null) (Description)

The updated description.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "generator_id": "string",
  • "prompt": "string",
  • "chain_of_thought_instructions": "string",
  • "id": "string",
  • "type": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string"
}

Delete Prompt

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

prompt_id
required
string (Prompt Id)

The unique identifier of the prompt.

Responses

Response samples

Content type
application/json
null

Build Prompt With Examples

Build a prompt with task instruction, requirements, and optional custom examples.

Uses the same formatting as the FewShotPromptBuilder but with user-provided examples.

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
Array of objects (Examples)
Default: []

Few-shot examples to include in the prompt.

Responses

Request samples

Content type
application/json
{
  • "examples": [ ]
}

Response samples

Content type
application/json
{
  • "prompt": "string"
}

Specs

Create Spec

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 120 ] characters

The name of the spec.

definition
required
string (Definition) non-empty

A detailed definition of the spec.

required
any (Properties)

The properties of the spec.

priority
integer (Priority)
Default: 1
Enum: 0 1 2 3

The priority of the spec.

status
string (SpecStatus)
Default: "active"
Enum: "active" "future" "deprecated" "archived"

The status of the spec.

tags
Array of strings (Tags)

The tags of the spec.

evaluate_full_trace
boolean (Evaluate Full Trace)
Default: false

Whether to evaluate the full trace instead of the final answer.

TaskSample (object) or null

An example task input/output pair.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "definition": "string",
  • "properties": {
    },
  • "priority": 0,
  • "status": "active",
  • "tags": [
    ],
  • "evaluate_full_trace": false,
  • "task_sample": {
    }
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "definition": "string",
  • "properties": {
    },
  • "priority": 0,
  • "status": "active",
  • "tags": [ ],
  • "eval_id": "string",
  • "task_sample": {
    },
  • "synthetic_data_generation_session_config": {
    },
  • "model_type": "string"
}

List Specs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Spec

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

spec_id
required
string (Spec Id)

The unique identifier of the spec.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "definition": "string",
  • "properties": {
    },
  • "priority": 0,
  • "status": "active",
  • "tags": [ ],
  • "eval_id": "string",
  • "task_sample": {
    },
  • "synthetic_data_generation_session_config": {
    },
  • "model_type": "string"
}

Update Spec

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

spec_id
required
string (Spec Id)

The unique identifier of the spec.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

The updated name.

Definition (string) or Definition (null) (Definition)

The updated definition.

Properties (any) or Properties (null) (Properties)

The updated spec properties.

Priority (integer) or null

The updated priority.

SpecStatus (string) or null

The updated status.

Array of Tags (strings) or Tags (null) (Tags)

The updated tags.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "definition": "string",
  • "properties": {
    },
  • "priority": 0,
  • "status": "active",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "definition": "string",
  • "properties": {
    },
  • "priority": 0,
  • "status": "active",
  • "tags": [ ],
  • "eval_id": "string",
  • "task_sample": {
    },
  • "synthetic_data_generation_session_config": {
    },
  • "model_type": "string"
}

Delete Spec

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

spec_id
required
string (Spec Id)

The unique identifier of the spec.

Responses

Response samples

Content type
application/json
null

Runs

Get Run

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

run_id
required
string (Run Id)

The unique identifier of the task run.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "input": "string",
  • "input_source": {
    },
  • "output": {
    },
  • "repair_instructions": "string",
  • "repaired_output": {
    },
  • "intermediate_outputs": {
    },
  • "tags": [ ],
  • "usage": {
    },
  • "cumulative_usage": {
    },
  • "trace": [
    ],
  • "parent_task_run_id": "string",
  • "model_type": "string"
}

Delete Run

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

run_id
required
string (Run Id)

The unique identifier of the task run.

Responses

Response samples

Content type
application/json
null

Update Run

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

run_id
required
string (Run Id)

The unique identifier of the task run.

Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "input": "string",
  • "input_source": {
    },
  • "output": {
    },
  • "repair_instructions": "string",
  • "repaired_output": {
    },
  • "intermediate_outputs": {
    },
  • "tags": [ ],
  • "usage": {
    },
  • "cumulative_usage": {
    },
  • "trace": [
    ],
  • "parent_task_run_id": "string",
  • "model_type": "string"
}

List Runs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Run

Create a TaskRun directly without running a model.

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
input
required
string (Input)

The input for the task run

output
required
string (Output)

The output for the task run

tags
Array of strings (Tags)
Default: []

Tags to apply to the task run

TaskOutputRating (object) or null

Optional rating for the output

model_name
required
string (Model Name)

The name of the model used to generate the data

model_provider
required
string (Model Provider)

The provider of the model used to generate the data

adapter_name
required
string (Adapter Name)

The name of the adapter used to generate the data

Responses

Request samples

Content type
application/json
{
  • "input": "string",
  • "output": "string",
  • "tags": [ ],
  • "rating": {
    },
  • "model_name": "string",
  • "model_provider": "string",
  • "adapter_name": "string"
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "input": "string",
  • "input_source": {
    },
  • "output": {
    },
  • "repair_instructions": "string",
  • "repaired_output": {
    },
  • "intermediate_outputs": {
    },
  • "tags": [ ],
  • "usage": {
    },
  • "cumulative_usage": {
    },
  • "trace": [
    ],
  • "parent_task_run_id": "string",
  • "model_type": "string"
}

List Run Summaries

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete Runs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
null

Execute Run

Invoke an AI model on a task and return the result. Unlike 'Create Run', this actually executes the model.

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
required
KilnAgentRunConfigProperties (object) or McpRunConfigProperties (object) (Run Config Properties)

The run configuration specifying model, prompt, and generation parameters.

Plaintext Input (string) or Plaintext Input (null) (Plaintext Input)

The task input as plaintext. Use for unstructured tasks.

Structured Input (object) or Array of Structured Input (any) or Structured Input (null) (Structured Input)

The task input as structured JSON. Use for tasks with an input schema.

Array of Tags (strings) or Tags (null) (Tags)

Tags to apply to the resulting task run.

Responses

Request samples

Content type
application/json
{
  • "run_config_properties": {
    },
  • "plaintext_input": "string",
  • "structured_input": { },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "input": "string",
  • "input_source": {
    },
  • "output": {
    },
  • "repair_instructions": "string",
  • "repaired_output": {
    },
  • "intermediate_outputs": {
    },
  • "tags": [ ],
  • "usage": {
    },
  • "cumulative_usage": {
    },
  • "trace": [
    ],
  • "parent_task_run_id": "string",
  • "model_type": "string"
}

Edit Run Tags

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: application/json
required
run_ids
required
Array of strings (Run Ids)

The list of task run IDs to edit.

Array of Add Tags (strings) or Add Tags (null) (Add Tags)

Tags to add to the task runs.

Array of Remove Tags (strings) or Remove Tags (null) (Remove Tags)

Tags to remove from the task runs.

Responses

Request samples

Content type
application/json
{
  • "run_ids": [
    ],
  • "add_tags": [
    ],
  • "remove_tags": [
    ]
}

Response samples

Content type
application/json
null

Bulk Upload Runs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Request Body schema: multipart/form-data
required
file
required
string <binary> (File)

The CSV file containing run data to import.

Splits (string) or Splits (null) (Splits)

JSON string mapping split names to numeric proportions (0-1).

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "filename": "string",
  • "imported_count": 0
}

List Run Tags

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

Responses

Response samples

Content type
application/json
{
  • "property1": 0,
  • "property2": 0
}

Feedback

List Feedback

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

run_id
required
string (Run Id)

The unique identifier of the task run.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Feedback

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

run_id
required
string (Run Id)

The unique identifier of the task run.

Request Body schema: application/json
required
feedback
required
string (Feedback) non-empty

Free-form text feedback on the task run.

source
required
string (FeedbackSource)
Enum: "run-page" "spec-feedback"

Where this feedback originated.

Responses

Request samples

Content type
application/json
{
  • "feedback": "string",
  • "source": "run-page"
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "feedback": "string",
  • "source": "run-page",
  • "model_type": "string"
}

Delete Feedback

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

task_id
required
string (Task Id)

The unique identifier of the task within the project.

run_id
required
string (Run Id)

The unique identifier of the task run.

feedback_id
required
string (Feedback Id)

The unique identifier of the feedback.

Responses

Response samples

Content type
application/json
null

Documents

Bulk Create Documents

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: multipart/form-data
Array of Files (strings) or Files (null) (Files)

The files to upload.

Array of Names (strings) or Names (null) (Names)

Optional names for the files.

Array of Tags (strings) or Tags (null) (Tags)

Tags to apply to all created documents.

Responses

Response samples

Content type
application/json
{
  • "created_documents": [
    ],
  • "failed_files": [
    ]
}

List Documents

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

query Parameters
Tags (string) or Tags (null) (Tags)

Comma-separated list of tags to filter by.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Extractions for Extractor Config

Return mapping of document id to list of extractions for the given extractor config id.

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

extractor_config_id
required
string (Extractor Config Id)

The unique identifier of the extractor configuration.

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

List Document Tags

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get Document Tag Counts

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
{
  • "property1": 0,
  • "property2": 0
}

Get Document

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "name_override": "string",
  • "description": "string",
  • "original_file": {
    },
  • "kind": "document",
  • "tags": [
    ],
  • "model_type": "string",
  • "friendly_name": "string"
}

Patch Document

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

Request Body schema: application/json
required
Name Override (string) or Name Override (null) (Name Override)

A name for this document.

Description (string) or Description (null) (Description)

The description of the document

Array of Tags (strings) or Tags (null) (Tags)

Tags for the document

Responses

Request samples

Content type
application/json
{
  • "name_override": "string",
  • "description": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "name_override": "string",
  • "description": "string",
  • "original_file": {
    },
  • "kind": "document",
  • "tags": [
    ],
  • "model_type": "string",
  • "friendly_name": "string"
}

Delete Document

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

Responses

Response samples

Content type
application/json
{ }

Edit Tags

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
document_ids
required
Array of strings (Document Ids)

List of document IDs to modify tags for.

Array of Add Tags (strings) or Add Tags (null) (Add Tags)

Tags to add to the documents.

Array of Remove Tags (strings) or Remove Tags (null) (Remove Tags)

Tags to remove from the documents.

Responses

Request samples

Content type
application/json
{
  • "document_ids": [
    ],
  • "add_tags": [
    ],
  • "remove_tags": [
    ]
}

Response samples

Content type
application/json
{
  • "property1": true,
  • "property2": true
}

Create Extractor Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

A name for this entity.

Description (string) or Description (null) (Description)

The description of the extractor config

model_provider_name
required
string (ModelProviderName)
Enum: "openai" "groq" "amazon_bedrock" "ollama" "openrouter" "fireworks_ai" "kiln_fine_tune" "kiln_custom_registry" "openai_compatible" "anthropic" "gemini_api" "azure_openai" "huggingface" "vertex" "together_ai" "siliconflow_cn" "cerebras" "docker_model_runner"

The name of the model provider to use for the extractor config.

model_name
required
string (Model Name)

The name of the model to use for the extractor config.

output_format
required
string (OutputFormat)
Enum: "text/plain" "text/markdown"

The output format of the extractor config

passthrough_mimetypes
Array of strings (Passthrough Mimetypes)
Items Enum: "text/plain" "text/markdown"

MIME types that bypass extraction and return the file content as-is.

required
object (LitellmExtractorConfigProperties)

The properties of the extractor config, specific to the selected extractor_type.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "model_provider_name": "openai",
  • "model_name": "string",
  • "output_format": "text/plain",
  • "passthrough_mimetypes": [
    ],
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "is_archived": false,
  • "description": "string",
  • "model_provider_name": "string",
  • "model_name": "string",
  • "output_format": "text/plain",
  • "passthrough_mimetypes": [
    ],
  • "extractor_type": "litellm",
  • "properties": {
    },
  • "model_type": "string"
}

Get Extractor Configs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Extractor Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

extractor_config_id
required
string (Extractor Config Id)

The unique identifier of the extractor configuration.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "is_archived": false,
  • "description": "string",
  • "model_provider_name": "string",
  • "model_name": "string",
  • "output_format": "text/plain",
  • "passthrough_mimetypes": [
    ],
  • "extractor_type": "litellm",
  • "properties": {
    },
  • "model_type": "string"
}

Patch Extractor Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

extractor_config_id
required
string (Extractor Config Id)

The unique identifier of the extractor configuration.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

A name for this entity.

Description (string) or Description (null) (Description)

The description of the extractor config

Is Archived (boolean) or Is Archived (null) (Is Archived)

Whether the extractor config is archived

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "is_archived": true
}

Response samples

Content type
application/json
{ }

Run Extractor Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

extractor_config_id
required
string (Extractor Config Id)

The unique identifier of the extractor configuration.

query Parameters
Tags (string) or Tags (null) (Tags)

Comma-separated list of tags to filter documents by.

Responses

Response samples

Content type
application/json
null

Get Extractions

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Extraction

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

extraction_id
required
string (Extraction Id)

The unique identifier of the extraction.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "source": "string",
  • "output_content": "string",
  • "extractor": {
    },
  • "output_content_truncated": true
}

Delete Extraction

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

extraction_id
required
string (Extraction Id)

The unique identifier of the extraction.

Responses

Response samples

Content type
application/json
{ }

Download Document File

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

Responses

Response samples

Content type
application/json
null

Download Extraction

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

extraction_id
required
string (Extraction Id)

The unique identifier of the extraction.

Responses

Response samples

Content type
application/json
null

Open Document Enclosing Folder

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

Responses

Response samples

Content type
application/json
{
  • "path": "string"
}

Delete Documents

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{ }

Get Extraction Progress

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

extractor_config_id
required
string (Extractor Config Id)

The unique identifier of the extractor configuration.

Responses

Response samples

Content type
application/json
{
  • "document_count_total": 0,
  • "document_count_successful": 0,
  • "extractor_config": {
    }
}

Extract File

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

document_id
required
string (Document Id)

The unique identifier of the document.

Request Body schema: application/json
Any of
Array
Any of
string

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
null

Create Chunker Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

A name for this entity.

Description (string) or Description (null) (Description)

The description of the chunker config

chunker_type
required
string (ChunkerType)
Enum: "fixed_window" "semantic"

The type of the chunker

required
any (Properties)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "chunker_type": "fixed_window",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "chunker_type": "fixed_window",
  • "properties": {
    },
  • "model_type": "string"
}

Get Chunker Configs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Embedding Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

A name for this entity.

Description (string) or Description (null) (Description)

The description of the embedding config

model_provider_name
required
string (ModelProviderName)
Enum: "openai" "groq" "amazon_bedrock" "ollama" "openrouter" "fireworks_ai" "kiln_fine_tune" "kiln_custom_registry" "openai_compatible" "anthropic" "gemini_api" "azure_openai" "huggingface" "vertex" "together_ai" "siliconflow_cn" "cerebras" "docker_model_runner"

The provider of the embedding model

model_name
required
string (Model Name)

The name of the embedding model

object (EmbeddingProperties)

Properties to be used to execute the embedding config.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "model_provider_name": "openai",
  • "model_name": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "model_provider_name": "openai",
  • "model_name": "string",
  • "properties": {
    },
  • "model_type": "string"
}

Get Embedding Configs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Reranker Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

A name for this entity.

Description (string) or Description (null) (Description)

The description of the reranker config

top_n
required
integer (Top N) > 0

Number of results to return from the reranker

model_provider_name
required
string (ModelProviderName)
Enum: "openai" "groq" "amazon_bedrock" "ollama" "openrouter" "fireworks_ai" "kiln_fine_tune" "kiln_custom_registry" "openai_compatible" "anthropic" "gemini_api" "azure_openai" "huggingface" "vertex" "together_ai" "siliconflow_cn" "cerebras" "docker_model_runner"

The name of the model provider to use for the reranker config.

model_name
required
string (Model Name)

The name of the model to use for the reranker config.

object (CohereCompatibleProperties)
Default: {"type":"cohere_compatible"}

The properties of the reranker config.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "top_n": 0,
  • "model_provider_name": "openai",
  • "model_name": "string",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "top_n": 0,
  • "model_provider_name": "string",
  • "model_name": "string",
  • "properties": {
    },
  • "model_type": "string"
}

Get Reranker Configs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Embedding Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

embedding_config_id
required
string (Embedding Config Id)

The unique identifier of the embedding configuration.

Responses

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "model_provider_name": "openai",
  • "model_name": "string",
  • "properties": {
    },
  • "model_type": "string"
}

Create Vector Store Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

A name for this entity.

Description (string) or Description (null) (Description)

The description of the vector store config

store_type
required
string (VectorStoreType)
Enum: "lancedb_fts" "lancedb_hybrid" "lancedb_vector"

The type of vector store to use

required
LanceDBConfigFTSPropertiesPublic (object) or LanceDBConfigVectorPropertiesPublic (object) or LanceDBConfigHybridPropertiesPublic (object) (Properties)

The properties of the vector store config, specific to the selected store_type.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "store_type": "lancedb_fts",
  • "properties": {
    }
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "description": "string",
  • "store_type": "lancedb_fts",
  • "properties": {
    },
  • "model_type": "string"
}

Get Vector Store Configs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Rag Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

rag_config_id
required
string (Rag Config Id)

The unique identifier of the RAG configuration.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

The updated name.

Description (string) or Description (null) (Description)

The updated description.

Is Archived (boolean) or Is Archived (null) (Is Archived)

Whether the config is archived.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "is_archived": true
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "is_archived": false,
  • "description": "string",
  • "tool_name": "string",
  • "tool_description": "string",
  • "extractor_config_id": "string",
  • "chunker_config_id": "string",
  • "embedding_config_id": "string",
  • "vector_store_config_id": "string",
  • "reranker_config_id": "string",
  • "tags": [
    ],
  • "model_type": "string"
}

Get Rag Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

rag_config_id
required
string (Rag Config Id)

The unique identifier of the RAG configuration.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "description": "string",
  • "tool_name": "string",
  • "tool_description": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "is_archived": true,
  • "extractor_config": {
    },
  • "chunker_config": {
    },
  • "embedding_config": {
    },
  • "vector_store_config": {
    },
  • "reranker_config": {
    },
  • "tags": [
    ]
}

Create Rag Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

A name for this entity.

Description (string) or Description (null) (Description)

A description for your own reference.

tool_name
required
string (Tool Name)

A name for the model to identify the Search Tool in conversations.

tool_description
required
string (Tool Description)

A description of the purpose of the tool. The model will use this description to understand the tool's capabilities.

required
Extractor Config Id (string) or Extractor Config Id (null) (Extractor Config Id)

The extractor config to use for the RAG workflow

required
Chunker Config Id (string) or Chunker Config Id (null) (Chunker Config Id)

The chunker config to use for the RAG workflow.

required
Embedding Config Id (string) or Embedding Config Id (null) (Embedding Config Id)

The embedding config to use for the RAG workflow.

required
Vector Store Config Id (string) or Vector Store Config Id (null) (Vector Store Config Id)

The vector store config to use for the RAG workflow.

Reranker Config Id (string) or Reranker Config Id (null) (Reranker Config Id)

The reranker config to use for the RAG workflow.

Array of Tags (strings) or Tags (null) (Tags)

List of document tags to filter by. If None, all documents in the project are used.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "tool_name": "string",
  • "tool_description": "string",
  • "extractor_config_id": "string",
  • "chunker_config_id": "string",
  • "embedding_config_id": "string",
  • "vector_store_config_id": "string",
  • "reranker_config_id": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "v": 1,
  • "id": "string",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string",
  • "is_archived": false,
  • "description": "string",
  • "tool_name": "string",
  • "tool_description": "string",
  • "extractor_config_id": "string",
  • "chunker_config_id": "string",
  • "embedding_config_id": "string",
  • "vector_store_config_id": "string",
  • "reranker_config_id": "string",
  • "tags": [
    ],
  • "model_type": "string"
}

Get Rag Configs

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Run Rag Config

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

rag_config_id
required
string (Rag Config Id)

The unique identifier of the RAG configuration.

Responses

Response samples

Content type
application/json
null

Get Rag Config Progress

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Request Body schema: application/json
required
Array of Rag Config Ids (strings) or Rag Config Ids (null) (Rag Config Ids)

The RAG config ids to get progress for, if left empty, progress for all RAG configs in the project will be returned

Responses

Request samples

Content type
application/json
{
  • "rag_config_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Search Rag Config

Search the vector store associated with a RAG config.

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

rag_config_id
required
string (Rag Config Id)

The unique identifier of the RAG configuration.

Request Body schema: application/json
required
query
required
string (Query)

The search query text

Responses

Request samples

Content type
application/json
{
  • "query": "string"
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Check Library State

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

Responses

Response samples

Content type
application/json
{
  • "is_empty": true
}

Ephemeral Split Document

Return chunks for a document extraction using FixedWindowChunker without persisting.

If chunk_size is None, return a single chunk with the full extraction output. chunk_overlap defaults to 0 when not provided.

path Parameters
project_id
required
string (Project Id)

The unique identifier of the project.

extractor_config_id
required
string (Extractor Config Id)

The unique identifier of the extractor configuration.

document_id
required
string (Document Id)

The unique identifier of the document.

Request Body schema: application/json
required
Chunk Size (integer) or Chunk Size (null) (Chunk Size)

The size of each chunk in tokens. If None, return a single chunk with the full extraction output.

Chunk Overlap (integer) or Chunk Overlap (null) (Chunk Overlap)

The overlap between chunks in tokens. If None, use the default overlap for the chunker.

Responses

Request samples

Content type
application/json
{
  • "chunk_size": 0,
  • "chunk_overlap": 0
}

Response samples

Content type
application/json
{
  • "chunks": [
    ]
}