---
title: "Create Agent"
method: POST
path: "/v1/create_agent/"
tags: ["Public"]
---

# Create Agent

`POST /v1/create_agent/`

## Request

- Base URL: `https://api.koncile.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.koncile.ai/v1/create_agent/`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/koncile/apis/koncile-api/docs/v1/create_agent/post.ts> (a function with typed inputs; its response is checked against the schema)

Create an agent on one or more templates.

Recreates an agent from a saved configuration, so a template backed up
outside Koncile can be rebuilt without duplicating an existing one.

**Reference data is a second step.** A `datatable_match` agent needs its
CSV before it can run, and cannot be activated without one. The full flow
is: `create_agent` (inactive) -> `upload_csv` -> `activate_agent`. Types
with no reference data (`splitting`, `document_rename`, `signature`,
`cross_split`) can be created active in one call.

`fraud` agents cannot be created here.

## Request body

- AgentApiCreate: Payload for `POST /v1/create_agent/`. No ``company_id`` / ``user_id``: both are taken from the authenticated API key, as every other public create endpoint does.
  - `type` 'compliance' | 'datatable_match' | 'fraud' | 'signature' | 'document_rename' | 'splitting' | 'cross_split', required
  - `template_ids` integer[], required: Templates to link. Exactly one for `datatable_match` and `compliance`; at least two for `cross_split`.
  - `name` string, nullable
  - `status` 'active' | 'inactive'
  - `settings` object, nullable: Type-specific configuration
  - `linked_field_ids` integer[]: Fields the agent should read
  - `field_mapping` AgentApiFieldMapping[]: Field roles, for `compliance`. Sets `agent_field` on each named field, so these fields are also linked.
    - `field_id` integer, required: Id of the field this mapping applies to
    - `agent_field` 'label' | 'code' | 'unit_price' | 'total_price' | 'quantity' | 'invoice_date' | 'invoice_amount' | 'invoice_number', required

## Response `201`

Successful Response

- AgentApiOut: An agent as the public API exposes it.
  - `id` integer, required
  - `type` 'compliance' | 'datatable_match' | 'fraud' | 'signature' | 'document_rename' | 'splitting' | 'cross_split', required
  - `name` string, nullable
  - `status` 'active' | 'inactive', required
  - `is_locked` boolean, nullable
  - `is_show_hint` boolean, nullable
  - `template_ids` integer[]: Templates this agent is linked to. Exactly one for `datatable_match` and `compliance`; at least two for `cross_split`.
  - `settings` object, nullable: Type-specific configuration. For `fraud` agents this is filtered: Koncile-internal rules and prompts are not exposed.
  - `linked_field_ids` integer[]: Fields the agent reads
  - `field_mapping` AgentApiFieldMapping[]: Field roles; populated for `compliance` agents
    - `field_id` integer, required: Id of the field this mapping applies to
    - `agent_field` 'label' | 'code' | 'unit_price' | 'total_price' | 'quantity' | 'invoice_date' | 'invoice_amount' | 'invoice_number', required
  - `datatable_ref` AgentApiDatatableRef: Pointer to a datatable-match agent's reference data. ``document_id`` is null until a CSV has been uploaded *and* processed — the row is written by the worker, not by the upload request, so a freshly uploaded agent reads as null for a few seconds. Deliberately does not repeat ``columns`` / ``has_header``: both already live in ``settings``, and a second copy is a thing to keep in sync for no gain.
    - `document_id` integer, nullable: Document holding the uploaded reference CSV; null if none loaded yet
  - `source_agent_id` integer, nullable: Read-only provenance if this agent was duplicated
  - `source_agent_name` string, nullable
  - `activation_error` string, nullable: Set only on `create_agent` when `status: active` was requested but the agent is not yet ready to activate. The agent exists and is inactive; fix the reason and call `activate_agent`.

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-25** `1446f41e0cd4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/koncile/apis/koncile-api/changes/v1/create_agent/post.md)

---

[API](https://skmtc.dev/koncile/apis/koncile-api.md) - [All operations](https://skmtc.dev/koncile/apis/koncile-api/llms.txt) - [OpenAPI document](https://skmtc.dev/koncile/apis/koncile-api/revisions/37187db89a87?raw)