Skip to main content
POST
Create an agent

Authorizations

Authorization
string
header
required

A VisIQ API key presented as Authorization: Bearer vq_prod_.... Mint harness keys under Settings → Harness Keys and API keys under Settings → API Keys in the dashboard.

Headers

Idempotency-Key
string

Optional. Makes this write safe to retry: a repeat with the same key, method, path (including its query string) and body within 24 hours returns the stored response with X-Idempotent-Replayed: true instead of running again. Reusing the key with a different request is a 422; a repeat while the first is still running is a 409, until the first request's 2-minute processing lease expires, after which the repeat runs. See REST conventions.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9_-]+$
X-Idempotency-Key
string

The legacy spelling of Idempotency-Key, accepted with the same behaviour. Sending both with different values is a 400.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9_-]+$

Body

application/json
agent_id
string
required
Required string length: 1 - 255
name
string
required
Required string length: 1 - 255
description
string
Maximum string length: 1000
mode
enum<string> | null
Available options:
enforce,
monitor,
off,
null
mode_by_operation
object | null

Per-operation mode overrides (any subset of the three keys).

api_key
string

Optional caller-supplied key; if omitted, one is generated and returned once.

Required string length: 16 - 256
owner_email
string<email>
Maximum string length: 320
agent_type
enum<string>
Available options:
langchain,
openclaw,
llamaindex,
autogen,
crewai,
semantic_kernel,
vercel_ai,
mastra,
voltagent,
openai_agents,
claude-code,
unknown
hitl_pathway
enum<string>
Available options:
slack,
teams,
email
trust_tier
string

A trust-tier identifier constrained server-side.

categories
string[]

Agent categories constrained server-side.

no_coverage
enum<string> | null
Available options:
open,
closed,
null
fail_mode
enum<string> | null

Per-agent override of what happens when the engine cannot decide. null uses the organization default.

Available options:
open,
closed,
null

Response

The created agent, including the one-time API key.

api_key
string
required

The one-time plaintext key. Store it now; it cannot be retrieved again.

id
string<uuid>
agent_id
string
name
string
description
string | null
mode
enum<string> | null
Available options:
enforce,
monitor,
off,
null
mode_by_operation
object | null

Per-operation mode overrides (any subset of the three keys).

owner_email
string | null
hitl_pathway
string | null
agent_os
string | null
agent_hostname
string | null
agent_ip
string | null
agent_username
string | null
trust_tier
string | null
categories
string[] | null
business_function
string | null
business_functions
string[] | null
business_function_source
string | null
no_coverage
string | null
created_at
string<date-time>
updated_at
string<date-time>