Create, manage, version, deploy, and build agents from source code

Agents

Agents are the core configuration unit in 9thSense. An agent defines which document types to collect, how to classify them, what cross-matching rules apply, and what pipeline steps to run. All agent state is version-snapshotted on every update.

Agent Object

idstring

UUID of the agent.

tenant_idstring

Tenant this agent belongs to.

goalstring

Unique slug identifier (e.g. "kyc_verification"). Used to route cases and pipeline runs.

namestring

Human-readable display name.

versionstring

Semantic version string (e.g. "1", "1.2").

definitionobject

Agent configuration JSONB. Contains doc_type_map, classify_aliases, cross_match, pipeline_per_type, intelligence_level, and other keys.

allow_cloudboolean

Whether this agent may route to cloud models when local models are unavailable.

deployedboolean

Whether the agent is active. Only deployed agents can receive new cases or pipeline runs.

created_atstring

ISO 8601 timestamp.

updated_atstring

ISO 8601 timestamp of last update.

CRUD Endpoints

Create Agent

POST /v1/agents

Requires scope: write. Returns 409 if an agent with the same goal and tenant_id already exists.

Request body:

goalstringrequired

Unique slug for this agent (snake_case, e.g. "kyc_verification").

namestringrequired

Human-readable name.

tenant_idstring

Tenant to associate this agent with.

definitionobject

Agent definition JSONB. See definition schema below.

versionstring

Version string. Defaults to "1".

allow_cloudboolean

Allow routing to cloud models. Default false.

deployedboolean

Whether to activate the agent immediately. Default false.

Example request:

{
  "goal": "kyc_verification",
  "name": "KYC Verification",
  "tenant_id": "acme-corp",
  "definition": {
    "doc_type_map": { "pan_card": "pan_card", "aadhaar": "aadhaar" },
    "classify_aliases": { "pan": "pan_card", "aadhaar card": "aadhaar" },
    "cross_match": {
      "enabled": true,
      "match_fields": ["name", "date_of_birth"],
      "min_doc_types": 2
    },
    "pipeline_per_type": ["classify", "extract", "validate"]
  },
  "deployed": true
}

Response (201): Agent object.

List Agents

GET /v1/agents

Requires scope: read.

Query parameters:

tenant_idstring

Filter by tenant. Returns all tenants if empty.

Response (200): Array of Agent objects.

Get Agent

GET /v1/agents/{agent_id}

Requires scope: read. Returns 404 if not found.

Path parameters:

agent_idstringrequired

UUID of the agent.

Update Agent

PUT /v1/agents/{agent_id}

Requires scope: write. Automatically snapshots the current state before applying the update. Returns 404 if not found.

Request body: Same fields as Create (all optional on update).

namestring
definitionobject
versionstring
allow_cloudboolean
deployedboolean

Delete Agent

DELETE /v1/agents/{agent_id}

Requires scope: write. Returns 204 No Content. Removes the agent from the in-memory cache and prevents new cases from routing to it.

Deploy / Undeploy Agent

PATCH /v1/agents/{agent_id}/deploy?deploy=true

Requires scope: write. Toggles the deployed flag without a full update.

Query parameters:

deploybooleanrequired

true to deploy, false to undeploy.

Version Endpoints

Every PUT (update) and rollback automatically snapshots the prior state. Snapshots accumulate in the agent_versions table.

List Agent Versions

GET /v1/agents/{agent_id}/versions

Requires scope: read.

Response (200): Array of version objects.

idstring
UUID of the version snapshot.
agent_idstring
Parent agent UUID.
tenant_idstring
versionstring
Version string at the time of snapshot.
namestring
definitionobject
notestring
Auto-generated note (e.g. "auto-snapshot before rollback to version 2").
created_atstring

Rollback Agent

POST /v1/agents/{agent_id}/rollback/{version_id}

Requires scope: write. Restores the agent to a prior snapshot. Automatically snapshots the current state before rolling back so the rollback is itself reversible. Returns the updated Agent object.

Path parameters:

agent_idstringrequired
UUID of the agent.
version_idstringrequired
UUID of the target version snapshot.

Builder Endpoints

The builder endpoints provide automated agent creation workflows — either from existing document types or from raw document samples.

Build Agent from Document Types

POST /v1/agents/build

Requires scope: write. Generates a complete agent definition from a list of existing document type IDs. Auto-generates doc_type_map, classify_aliases, and detects cross-match fields from the document types' output schemas.

Request body:

namestringrequired

Agent display name.

context_idsstring[]required

List of document type IDs to include (must exist in the system).

tenant_idstring
goalstring

Override the auto-generated goal slug.

cross_match_fieldsstring[]

Override auto-detected cross-match fields.

pipelinestring[]

Pipeline steps per document type. Default: ["classify", "extract", "validate"].

deployboolean

Deploy the agent immediately after creation. Default false.

Example request:

{
  "name": "KYC Verification",
  "context_ids": ["pan_card", "aadhaar"],
  "tenant_id": "acme-corp",
  "deploy": true
}

Response (200):

{
  "agent": { ... },
  "contexts_existing": ["pan_card", "aadhaar"],
  "contexts_created": []
}

Discover and Build Agent

POST /v1/agents/discover

Requires scope: write. Upload raw document samples — 9thSense uses a VLM to classify and extract each document, discovers their types, creates any missing document type configurations, and builds a complete agent automatically.

Request body:

documentsobject[]required

Array of document objects, each with data (base64) and mime_type.

tenant_idstring
namestring

Override the auto-generated agent name.

cross_match_fieldsstring[]

Override auto-detected cross-match fields.

pipelinestring[]

Pipeline steps. Default: ["classify", "extract", "validate"].

deployboolean

Deploy the agent immediately. Default false.

Response (200):

{
  "agent": { ... },
  "contexts_created": ["driving_license"],
  "contexts_existing": ["pan_card"]
}

Builder Wizard Endpoints

The wizard is a stateful, multi-step builder session for interactive agent construction.

Start Builder Session

POST /v1/agents/builder/start

Requires scope: write. Returns 201.

tenant_idstring
modestring
Builder mode ("guided", "expert").

Get Builder Session

GET /v1/agents/builder/{builder_id}

Requires scope: read.

Perform Builder Action

POST /v1/agents/builder/{builder_id}/action

Requires scope: write.

actionstringrequired
Action name to perform in the wizard step.
paramsobject
Action parameters.

Builder Chat

POST /v1/agents/builder/{builder_id}/chat

Requires scope: write. Conversational turn within a builder session.

messagestringrequired
User message.
attachmentsobject[]
Optional document attachments (base64 + mime_type).

Response:

replystring
Assistant reply.
stateobject
Updated builder session state.
PreviousAuthenticationNextCases