agent4.io
For developers · tenant-level

REST API

Everything the console can do, over HTTP. Most people don’t need this — point a coding agent at the MCP + skills and describe the task. Call it directly when you’re building your own backend.

New to this? A “coding agent” — Claude Code, Cursor, Codex — is an AI that writes code for you.

Authentication

Base URL https://api.agent4.io/v1. Every tenant endpoint authenticates with your API key:

X-API-Key: tk_…            # or:  Authorization: Bearer tk_…

Generate a key in the console under Settings → Security — the plaintext is shown once, at creation. Every endpoint below lists its parameters, request body and response, generated from the live spec: openapi.json · interactive /docs.

Agents

An agent is soul + task + tools + skills + knowledge_bases. System tools (current_time, ip_geo, weather) are enabled by default on new agents.

GET/agents

List your agents (name, alias, published).

Parameters
publishedquerybooleanoptional
Response · 200 · AgentSummary[]
namestringrequiredName
idstringrequiredId
aliasstring?optionalAlias
publishedbooleanoptionalPublished
sourcestringoptionalSource
modelstring?optionalModel
taskstring?optionalTask
tools_countintegeroptionalTools Count
skills_countintegeroptionalSkills Count
toolsstring[]optionalTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
Example response
[
  {
    "name": "string",
    "id": "string",
    "alias": "string",
    "published": true,
    "source": "string",
    "model": "string",
    "task": "string",
    "tools_count": 0,
    "skills_count": 0,
    "tools": [
      "string"
    ],
    "skills": [
      "string"
    ],
    "knowledge_bases": [
      "string"
    ]
  }
]
DELETE/agents/{name}

Delete an agent.

Parameters
namepathstringrequired

Response 204 — No Content (success, empty body).

GET/agents/{name}

Get one agent's full configuration.

Parameters
namepathstringrequired
Response · 200 · AgentOut
namestringrequiredName
idstring?optionalId
aliasstring?optionalAlias
soulstringrequiredSoul
taskstringrequiredTask
toolsstring[]requiredTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
sourcestringrequiredSource
Example response
{
  "name": "string",
  "id": "string",
  "alias": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ],
  "source": "string"
}
PATCH/agents/{name}

Partial update — only the fields you send change; the rest are left as-is.

Parameters
namepathstringrequired
Request body · JSON
soulstring?optionalSoul
taskstring?optionalTask
toolsstring[]?optionalTools
tools_addstring[]?optionalTools Add
tools_removestring[]?optionalTools Remove
skillsstring[]?optionalSkills
skills_addstring[]?optionalSkills Add
skills_removestring[]?optionalSkills Remove
knowledge_basesstring[]?optionalKnowledge Bases
knowledge_bases_addstring[]?optionalKnowledge Bases Add
knowledge_bases_removestring[]?optionalKnowledge Bases Remove
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedboolean?optionalPublished
greetingstring?optionalGreeting
auto_greetingboolean?optionalAuto Greeting
auto_suggestboolean?optionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsboolean?optionalAsk Forms
proactive_ctaboolean?optionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningboolean?optionalReasoning
grounding_requiredboolean?optionalGrounding Required
injection_guardboolean?optionalInjection Guard
public_sourcesboolean?optionalPublic Sources
ambiguity_checkboolean?optionalAmbiguity Check
deep_researchboolean?optionalDeep Research
on_demand_contextboolean?optionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
Example request
{
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "tools_add": [
    "string"
  ],
  "tools_remove": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "skills_add": [
    "string"
  ],
  "skills_remove": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "knowledge_bases_add": [
    "string"
  ],
  "knowledge_bases_remove": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ]
}
Response · 200 · AgentOut
namestringrequiredName
idstring?optionalId
aliasstring?optionalAlias
soulstringrequiredSoul
taskstringrequiredTask
toolsstring[]requiredTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
sourcestringrequiredSource
Example response
{
  "name": "string",
  "id": "string",
  "alias": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ],
  "source": "string"
}
curl -X PATCH https://api.agent4.io/v1/agents/advisor -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"knowledge_bases":["company-policy"],"grounding_required":true}'
POST/agents/{name}

Create an agent (409 if it exists).

Parameters
namepathstringrequired
Request body · JSON
soulstringoptionalSoul
taskstringoptionalTask
toolsstring[]optionalTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optional
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
Example request
{
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ]
}
Response · 201 · AgentOut
namestringrequiredName
idstring?optionalId
aliasstring?optionalAlias
soulstringrequiredSoul
taskstringrequiredTask
toolsstring[]requiredTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
sourcestringrequiredSource
Example response
{
  "name": "string",
  "id": "string",
  "alias": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ],
  "source": "string"
}
curl -X POST https://api.agent4.io/v1/agents/advisor -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"soul":"You are a loan advisor","task":"Answer from the knowledge base; never quote a rate.","tools":["web_search"],"knowledge_bases":["company-policy"],"published":true}'
PUT/agents/{name}

Create or replace — full-replace semantics; send every field you want to keep.

Parameters
namepathstringrequired
Request body · JSON
soulstringoptionalSoul
taskstringoptionalTask
toolsstring[]optionalTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optional
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
Example request
{
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ]
}
Response · 200 · AgentOut
namestringrequiredName
idstring?optionalId
aliasstring?optionalAlias
soulstringrequiredSoul
taskstringrequiredTask
toolsstring[]requiredTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
sourcestringrequiredSource
Example response
{
  "name": "string",
  "id": "string",
  "alias": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ],
  "source": "string"
}
GET/agents/{name}/alias

Get the agent's public human-readable slug + its full URL prefix.

Parameters
namepathstringrequired
Response · 200 · AgentAliasOut
aliasstring?optionalAlias
urlstring?optionalUrl
url_prefixstringoptionalUrl Prefix
Example response
{
  "alias": "string",
  "url": "string",
  "url_prefix": "string"
}
PUT/agents/{name}/alias

Set (or clear) the alias — the memorable public URL segment; validated + unique per tenant.

Parameters
namepathstringrequired
Request body · JSON
aliasstring?optionalAlias
Example request
{
  "alias": "string"
}
Response · 200 · AgentAliasOut
aliasstring?optionalAlias
urlstring?optionalUrl
url_prefixstringoptionalUrl Prefix
Example response
{
  "alias": "string",
  "url": "string",
  "url_prefix": "string"
}
curl -X PUT https://api.agent4.io/v1/agents/advisor/alias -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"alias":"advisor"}'
POST/agents/{name}/clone

Copy an agent into a new draft (unpublished, no alias).

Parameters
namepathstringrequired
Response · 201 · AgentOut
namestringrequiredName
idstring?optionalId
aliasstring?optionalAlias
soulstringrequiredSoul
taskstringrequiredTask
toolsstring[]requiredTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
sourcestringrequiredSource
Example response
{
  "name": "string",
  "id": "string",
  "alias": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ],
  "source": "string"
}
GET/agents/{name}/export

Export a portable agent JSON (config only; no tenant/version).

Parameters
namepathstringrequired
Response · 200 · AgentExport
schema_versionintegerrequiredSchema Version
kindstringoptionalKind
namestringrequiredName
soulstringoptionalSoul
taskstringoptionalTask
toolsstring[]optionalTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
Example response
{
  "schema_version": 0,
  "kind": "string",
  "name": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true
}
POST/agents/{name}/preview-plan

Preview Plan

Parameters
namepathstringrequired
Request body · JSON
goalstringrequiredGoal
Example request
{
  "goal": "string"
}
Response · 200 · PreviewPlanOut
planobjectrequiredPlan
backendstringrequiredBackend
warningsstring[]requiredWarnings
Example response
{
  "plan": {},
  "backend": "string",
  "warnings": [
    "string"
  ]
}
GET/agents/{name}/pwa

Get Agent Pwa

Parameters
namepathstringrequired
Response · 200 · PwaOut
install_promptstringoptionalInstall Prompt
favicon_urlstring?optionalFavicon Url
icon192_urlstring?optionalIcon192 Url
icon512_urlstring?optionalIcon512 Url
icon_maskable_urlstring?optionalIcon Maskable Url
Example response
{
  "install_prompt": "string",
  "favicon_url": "string",
  "icon192_url": "string",
  "icon512_url": "string",
  "icon_maskable_url": "string"
}
PATCH/agents/{name}/pwa

Patch Agent Pwa

Parameters
namepathstringrequired
Request body · JSON
install_promptstring?optionalInstall Prompt
Example request
{
  "install_prompt": "string"
}
Response · 200 · PwaOut
install_promptstringoptionalInstall Prompt
favicon_urlstring?optionalFavicon Url
icon192_urlstring?optionalIcon192 Url
icon512_urlstring?optionalIcon512 Url
icon_maskable_urlstring?optionalIcon Maskable Url
Example response
{
  "install_prompt": "string",
  "favicon_url": "string",
  "icon192_url": "string",
  "icon512_url": "string",
  "icon_maskable_url": "string"
}
DELETE/agents/{name}/pwa/icon

Clear Agent Pwa Icon

Parameters
namepathstringrequired
Response · 200 · PwaOut
install_promptstringoptionalInstall Prompt
favicon_urlstring?optionalFavicon Url
icon192_urlstring?optionalIcon192 Url
icon512_urlstring?optionalIcon512 Url
icon_maskable_urlstring?optionalIcon Maskable Url
Example response
{
  "install_prompt": "string",
  "favicon_url": "string",
  "icon192_url": "string",
  "icon512_url": "string",
  "icon_maskable_url": "string"
}
POST/agents/{name}/pwa/icon

Upload Agent Pwa Icon

Parameters
namepathstringrequired
Request body · multipart/form-data
filestringrequiredFile
Example request
{
  "file": "string"
}
Response · 200 · PwaOut
install_promptstringoptionalInstall Prompt
favicon_urlstring?optionalFavicon Url
icon192_urlstring?optionalIcon192 Url
icon512_urlstring?optionalIcon512 Url
icon_maskable_urlstring?optionalIcon Maskable Url
Example response
{
  "install_prompt": "string",
  "favicon_url": "string",
  "icon192_url": "string",
  "icon512_url": "string",
  "icon_maskable_url": "string"
}
GET/agents/{name}/revisions

Configuration revision history.

Parameters
namepathstringrequired
Response · 200 · app__api__agents__RevisionOut[]
idstringrequiredId
created_atstringrequiredCreated At
actorstring?optionalActor
snapshotobjectrequiredSnapshot
Example response
[
  {
    "id": "string",
    "created_at": "string",
    "actor": "string",
    "snapshot": {}
  }
]
POST/agents/{name}/revisions/{rev_id}/restore

Restore the agent to an earlier revision.

Parameters
namepathstringrequired
rev_idpathstringrequired
Response · 200 · AgentOut
namestringrequiredName
idstring?optionalId
aliasstring?optionalAlias
soulstringrequiredSoul
taskstringrequiredTask
toolsstring[]requiredTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
sourcestringrequiredSource
Example response
{
  "name": "string",
  "id": "string",
  "alias": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ],
  "source": "string"
}
POST/agents/{name}/test-planner-trigger

Test Planner Trigger

Parameters
namepathstringrequired
Request body · JSON
messagesstring[]requiredMessages
samplesintegeroptionalSamples
expectboolean?optionalExpect
Example request
{
  "messages": [
    "string"
  ],
  "samples": 0,
  "expect": true
}
Response · 200 · PlannerTriggerOut
triggeredintegerrequiredTriggered
samplesintegerrequiredSamples
goalsstring[]requiredGoals
domainstringrequiredDomain
matchedboolean?optionalMatched
Example response
{
  "triggered": 0,
  "samples": 0,
  "goals": [
    "string"
  ],
  "domain": "string",
  "matched": true
}
POST/agents/{name}/test-trigger

Dry-run a tool-call trigger test: replays your messages against the production prompt assembly, tool schemas and model routing, and reports per-sample whether the expected tool was actually called — plus claimed_without_call (the model said "noted" without calling). Tools are NOT executed and no session is stored; tokens count toward your quota. loaded=false tests the skill description (first turn), loaded=true simulates post-load_skill (tests instructions). Caps: messages ≤ 5, samples ≤ 5.

Parameters
namepathstringrequired
Request body · JSON
messagesstring[]requiredMessages
expect_toolstring?optionalExpect Tool
samplesintegeroptionalSamples
loadedbooleanoptionalLoaded
skillstring?optionalSkill
Example request
{
  "messages": [
    "string"
  ],
  "expect_tool": "string",
  "samples": 0,
  "loaded": true,
  "skill": "string"
}

Response 200 · object — unstructured JSON (no fixed schema).

curl -X POST https://api.agent4.io/v1/agents/advisor/test-trigger -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"messages":["My phone is 555 0123, call me back"],"expect_tool":"save_contact","samples":3,"loaded":true}'
POST/agents/import

Import an exported agent JSON as a new agent.

Request body · JSON
schema_versionintegeroptionalSchema Version
kindstringoptionalKind
namestringrequiredName
soulstringoptionalSoul
taskstringoptionalTask
toolsstring[]optionalTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
override_namestring?optionalOverride Name
Example request
{
  "schema_version": 0,
  "kind": "string",
  "name": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "override_name": "string"
}
Response · 201 · AgentOut
namestringrequiredName
idstring?optionalId
aliasstring?optionalAlias
soulstringrequiredSoul
taskstringrequiredTask
toolsstring[]requiredTools
skillsstring[]optionalSkills
knowledge_basesstring[]optionalKnowledge Bases
history_windowinteger?optionalHistory Window
max_output_tokensinteger?optionalMax Output Tokens
tool_call_max_tokensinteger?optionalTool Call Max Tokens
modelstring?optionalModel
publishedbooleanoptionalPublished
greetingstring?optionalGreeting
auto_greetingbooleanoptionalAuto Greeting
auto_suggestbooleanoptionalAuto Suggest
suggest_promptstring?optionalSuggest Prompt
ask_formsbooleanoptionalAsk Forms
proactive_ctabooleanoptionalProactive Cta
cta_promptstring?optionalCta Prompt
no_match_replystring?optionalNo Match Reply
reasoningbooleanoptionalReasoning
grounding_requiredbooleanoptionalGrounding Required
injection_guardbooleanoptionalInjection Guard
public_sourcesbooleanoptionalPublic Sources
ambiguity_checkbooleanoptionalAmbiguity Check
deep_researchbooleanoptionalDeep Research
on_demand_contextbooleanoptionalOn Demand Context
menu_itemsstring[]?optionalMenu Items
sourcestringrequiredSource
Example response
{
  "name": "string",
  "id": "string",
  "alias": "string",
  "soul": "string",
  "task": "string",
  "tools": [
    "string"
  ],
  "skills": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "history_window": 0,
  "max_output_tokens": 0,
  "tool_call_max_tokens": 0,
  "model": "string",
  "published": true,
  "greeting": "string",
  "auto_greeting": true,
  "auto_suggest": true,
  "suggest_prompt": "string",
  "ask_forms": true,
  "proactive_cta": true,
  "cta_prompt": "string",
  "no_match_reply": "string",
  "reasoning": true,
  "grounding_required": true,
  "injection_guard": true,
  "public_sources": true,
  "ambiguity_check": true,
  "deep_research": true,
  "on_demand_context": true,
  "menu_items": [
    "string"
  ],
  "source": "string"
}

Sharing & channels — make an agent reachable

published=true is visible, not reachable. Create a share to get a hosted chat page + QR + embed snippet; the /s/, /embed/ and /s/{token}/qr.svg URLs are public (no key).

GET/agents/{name}/shares

List an agent's shares.

Parameters
namepathstringrequired
Response · 200 · ShareOut[]
tokenstringrequiredToken
agentstringrequiredAgent
labelstringrequiredLabel
greetingstring?optionalGreeting
configWidgetConfigrequired
has_secretbooleanrequiredHas Secret
disabledbooleanrequiredDisabled
internalbooleanoptionalInternal
urlstringrequiredUrl
embed_urlstringrequiredEmbed Url
public_basestring?optionalPublic Base
css_warningsobject[]optionalCss Warnings
Example response
[
  {
    "token": "string",
    "agent": "string",
    "label": "string",
    "greeting": "string",
    "config": {},
    "has_secret": true,
    "disabled": true,
    "internal": true,
    "url": "string",
    "embed_url": "string",
    "public_base": "string",
    "css_warnings": [
      {}
    ]
  }
]
POST/agents/{name}/shares

Create a share/integration. Returns token, url (/s/<token>, a full-screen hosted chat page), embed_url and public_base.

Parameters
namepathstringrequired
Request body · JSON
labelstringoptionalLabel
greetingstring?optionalGreeting
configWidgetConfig?optional
Example request
{
  "label": "string",
  "greeting": "string",
  "config": {}
}
Response · 201 · ShareOut
tokenstringrequiredToken
agentstringrequiredAgent
labelstringrequiredLabel
greetingstring?optionalGreeting
configWidgetConfigrequired
has_secretbooleanrequiredHas Secret
disabledbooleanrequiredDisabled
internalbooleanoptionalInternal
urlstringrequiredUrl
embed_urlstringrequiredEmbed Url
public_basestring?optionalPublic Base
css_warningsobject[]optionalCss Warnings
Example response
{
  "token": "string",
  "agent": "string",
  "label": "string",
  "greeting": "string",
  "config": {},
  "has_secret": true,
  "disabled": true,
  "internal": true,
  "url": "string",
  "embed_url": "string",
  "public_base": "string",
  "css_warnings": [
    {}
  ]
}
curl -X POST https://api.agent4.io/v1/agents/advisor/shares -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"label":"Website widget"}'
DELETE/agents/{name}/shares/{token}

Revoke a share (add ?purge=true to also delete its data).

Parameters
namepathstringrequired
tokenpathstringrequired
purgequerybooleanoptional

Response 204 — No Content (success, empty body).

PATCH/agents/{name}/shares/{token}

Update a share (label, greeting, widget config, disabled).

Parameters
namepathstringrequired
tokenpathstringrequired
Request body · JSON
labelstring?optionalLabel
greetingstring?optionalGreeting
configWidgetConfig?optional
disabledboolean?optionalDisabled
Example request
{
  "label": "string",
  "greeting": "string",
  "config": {},
  "disabled": true
}
Response · 200 · ShareOut
tokenstringrequiredToken
agentstringrequiredAgent
labelstringrequiredLabel
greetingstring?optionalGreeting
configWidgetConfigrequired
has_secretbooleanrequiredHas Secret
disabledbooleanrequiredDisabled
internalbooleanoptionalInternal
urlstringrequiredUrl
embed_urlstringrequiredEmbed Url
public_basestring?optionalPublic Base
css_warningsobject[]optionalCss Warnings
Example response
{
  "token": "string",
  "agent": "string",
  "label": "string",
  "greeting": "string",
  "config": {},
  "has_secret": true,
  "disabled": true,
  "internal": true,
  "url": "string",
  "embed_url": "string",
  "public_base": "string",
  "css_warnings": [
    {}
  ]
}
POST/agents/{name}/shares/{token}/secret

Mint the host_session signing secret for a trusted-embed integration (shown once).

Parameters
namepathstringrequired
tokenpathstringrequired
Response · 200 · SecretOut
secretstringrequiredSecret
Example response
{
  "secret": "string"
}
DELETE/agents/{name}/telegram

Unbind Telegram.

Parameters
namepathstringrequired

Response 204 — No Content (success, empty body).

GET/agents/{name}/telegram

Get the agent's Telegram channel binding.

Parameters
namepathstringrequired
Response · 200 · TelegramStatusOut
connectedbooleanrequiredConnected
enabledbooleanoptionalEnabled
bot_usernamestring?optionalBot Username
bot_linkstring?optionalBot Link
has_tokenbooleanoptionalHas Token
Example response
{
  "connected": true,
  "enabled": true,
  "bot_username": "string",
  "bot_link": "string",
  "has_token": true
}
PUT/agents/{name}/telegram

Bind a Telegram bot (bot token) to this agent.

Parameters
namepathstringrequired
Request body · JSON
bot_tokenstringrequiredBot Token
Example request
{
  "bot_token": "string"
}
Response · 200 · TelegramStatusOut
connectedbooleanrequiredConnected
enabledbooleanoptionalEnabled
bot_usernamestring?optionalBot Username
bot_linkstring?optionalBot Link
has_tokenbooleanoptionalHas Token
Example response
{
  "connected": true,
  "enabled": true,
  "bot_username": "string",
  "bot_link": "string",
  "has_token": true
}
POST/agents/{name}/telegram/toggle

Enable / disable the Telegram channel.

Parameters
namepathstringrequired
Request body · JSON
enabledbooleanrequiredEnabled
Example request
{
  "enabled": true
}
Response · 200 · TelegramStatusOut
connectedbooleanrequiredConnected
enabledbooleanoptionalEnabled
bot_usernamestring?optionalBot Username
bot_linkstring?optionalBot Link
has_tokenbooleanoptionalHas Token
Example response
{
  "connected": true,
  "enabled": true,
  "bot_username": "string",
  "bot_link": "string",
  "has_token": true
}
DELETE/agents/{name}/whatsapp

Unbind WhatsApp.

Parameters
namepathstringrequired

Response 204 — No Content (success, empty body).

GET/agents/{name}/whatsapp

Get the agent's WhatsApp channel binding.

Parameters
namepathstringrequired
Response · 200 · WaStatusOut
connectedbooleanrequiredConnected
enabledbooleanoptionalEnabled
phone_number_idstring?optionalPhone Number Id
display_phonestring?optionalDisplay Phone
callback_urlstring?optionalCallback Url
verify_tokenstring?optionalVerify Token
has_tokenbooleanoptionalHas Token
Example response
{
  "connected": true,
  "enabled": true,
  "phone_number_id": "string",
  "display_phone": "string",
  "callback_url": "string",
  "verify_token": "string",
  "has_token": true
}
PUT/agents/{name}/whatsapp

Bind WhatsApp (provider credentials) to this agent.

Parameters
namepathstringrequired
Request body · JSON
phone_number_idstringrequiredPhone Number Id
access_tokenstringrequiredAccess Token
app_secretstringoptionalApp Secret
display_phonestring?optionalDisplay Phone
graph_versionstring?optionalGraph Version
Example request
{
  "phone_number_id": "string",
  "access_token": "string",
  "app_secret": "string",
  "display_phone": "string",
  "graph_version": "string"
}
Response · 200 · WaStatusOut
connectedbooleanrequiredConnected
enabledbooleanoptionalEnabled
phone_number_idstring?optionalPhone Number Id
display_phonestring?optionalDisplay Phone
callback_urlstring?optionalCallback Url
verify_tokenstring?optionalVerify Token
has_tokenbooleanoptionalHas Token
Example response
{
  "connected": true,
  "enabled": true,
  "phone_number_id": "string",
  "display_phone": "string",
  "callback_url": "string",
  "verify_token": "string",
  "has_token": true
}
POST/agents/{name}/whatsapp/toggle

Enable / disable the WhatsApp channel.

Parameters
namepathstringrequired
Request body · JSON
enabledbooleanrequiredEnabled
Example request
{
  "enabled": true
}
Response · 200 · WaStatusOut
connectedbooleanrequiredConnected
enabledbooleanoptionalEnabled
phone_number_idstring?optionalPhone Number Id
display_phonestring?optionalDisplay Phone
callback_urlstring?optionalCallback Url
verify_tokenstring?optionalVerify Token
has_tokenbooleanoptionalHas Token
Example response
{
  "connected": true,
  "enabled": true,
  "phone_number_id": "string",
  "display_phone": "string",
  "callback_url": "string",
  "verify_token": "string",
  "has_token": true
}
GET/embed/{token}

Public: the embeddable widget iframe (bubble / window / full).

Parameters
tokenpathstringrequired

Response 200 — No Content (success, empty body).

GET/s/{token}

Public: the standalone full-screen chat page — the link/QR you hand to end users (anonymous, remembered by browser).

Parameters
tokenpathstringrequired

Response 200 — No Content (success, empty body).

GET/s/{token}/manifest.webmanifest

Share Manifest

Parameters
tokenpathstringrequired

Response 200 · any

Example response
"…"
GET/s/{token}/qr.svg

Public: a QR (SVG) for the chat page — print it; no website needed.

Parameters
tokenpathstringrequired

Response 200 · any

Example response
"…"

Knowledge bases

Grounded, per-tenant sources, auto-retrieved every turn. Names are normalised to url-safe slugs on creation — use the returned name for documents, search and attaching.

GET/knowledge-bases

List knowledge bases (with document / chunk counts).

Response · 200 · KbOut[]
namestringrequiredName
kindstringoptionalKind
instructionsstringrequiredInstructions
descriptionstringrequiredDescription
max_distancenumber?requiredMax Distance
top_kinteger?optionalTop K
rerankbooleanoptionalRerank
recall_evalbooleanoptionalRecall Eval
documentsintegeroptionalDocuments
chunksintegeroptionalChunks
chunk_spreadinteger[]?optionalChunk Spread
edited_chunksintegeroptionalEdited Chunks
Example response
[
  {
    "name": "string",
    "kind": "string",
    "instructions": "string",
    "description": "string",
    "max_distance": 0,
    "top_k": 0,
    "rerank": true,
    "recall_eval": true,
    "documents": 0,
    "chunks": 0,
    "chunk_spread": [
      0
    ],
    "edited_chunks": 0
  }
]
DELETE/knowledge-bases/{name}

Delete a KB and everything derived from it.

Parameters
namepathstringrequired

Response 204 — No Content (success, empty body).

GET/knowledge-bases/{name}

Get a KB's config (instructions, description, relevance floor).

Parameters
namepathstringrequired
Response · 200 · KbOut
namestringrequiredName
kindstringoptionalKind
instructionsstringrequiredInstructions
descriptionstringrequiredDescription
max_distancenumber?requiredMax Distance
top_kinteger?optionalTop K
rerankbooleanoptionalRerank
recall_evalbooleanoptionalRecall Eval
documentsintegeroptionalDocuments
chunksintegeroptionalChunks
chunk_spreadinteger[]?optionalChunk Spread
edited_chunksintegeroptionalEdited Chunks
Example response
{
  "name": "string",
  "kind": "string",
  "instructions": "string",
  "description": "string",
  "max_distance": 0,
  "top_k": 0,
  "rerank": true,
  "recall_eval": true,
  "documents": 0,
  "chunks": 0,
  "chunk_spread": [
    0
  ],
  "edited_chunks": 0
}
PATCH/knowledge-bases/{name}

Patch Kb

Parameters
namepathstringrequired
Request body · JSON
instructionsstring?optionalInstructions
descriptionstring?optionalDescription
max_distancenumber?optionalMax Distance
top_kinteger?optionalTop K
rerankboolean?optionalRerank
recall_evalboolean?optionalRecall Eval
Example request
{
  "instructions": "string",
  "description": "string",
  "max_distance": 0,
  "top_k": 0,
  "rerank": true,
  "recall_eval": true
}
Response · 200 · KbOut
namestringrequiredName
kindstringoptionalKind
instructionsstringrequiredInstructions
descriptionstringrequiredDescription
max_distancenumber?requiredMax Distance
top_kinteger?optionalTop K
rerankbooleanoptionalRerank
recall_evalbooleanoptionalRecall Eval
documentsintegeroptionalDocuments
chunksintegeroptionalChunks
chunk_spreadinteger[]?optionalChunk Spread
edited_chunksintegeroptionalEdited Chunks
Example response
{
  "name": "string",
  "kind": "string",
  "instructions": "string",
  "description": "string",
  "max_distance": 0,
  "top_k": 0,
  "rerank": true,
  "recall_eval": true,
  "documents": 0,
  "chunks": 0,
  "chunk_spread": [
    0
  ],
  "edited_chunks": 0
}
POST/knowledge-bases/{name}

Create a KB (name in the path is slugified; returned name is canonical).

Parameters
namepathstringrequired
Request body · JSON
instructionsstringoptionalInstructions
descriptionstringoptionalDescription
max_distancenumber?optionalMax Distance
top_kinteger?optionalTop K
rerankbooleanoptionalRerank
recall_evalbooleanoptionalRecall Eval
kindstringoptionalKind
Example request
{
  "instructions": "string",
  "description": "string",
  "max_distance": 0,
  "top_k": 0,
  "rerank": true,
  "recall_eval": true,
  "kind": "string"
}
Response · 201 · KbOut
namestringrequiredName
kindstringoptionalKind
instructionsstringrequiredInstructions
descriptionstringrequiredDescription
max_distancenumber?requiredMax Distance
top_kinteger?optionalTop K
rerankbooleanoptionalRerank
recall_evalbooleanoptionalRecall Eval
documentsintegeroptionalDocuments
chunksintegeroptionalChunks
chunk_spreadinteger[]?optionalChunk Spread
edited_chunksintegeroptionalEdited Chunks
Example response
{
  "name": "string",
  "kind": "string",
  "instructions": "string",
  "description": "string",
  "max_distance": 0,
  "top_k": 0,
  "rerank": true,
  "recall_eval": true,
  "documents": 0,
  "chunks": 0,
  "chunk_spread": [
    0
  ],
  "edited_chunks": 0
}
curl -X POST https://api.agent4.io/v1/knowledge-bases/company-policy -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"instructions":"Authoritative current policy; overrides industry norms."}'
PUT/knowledge-bases/{name}

Update a KB's config.

Parameters
namepathstringrequired
Request body · JSON
instructionsstringoptionalInstructions
descriptionstringoptionalDescription
max_distancenumber?optionalMax Distance
top_kinteger?optionalTop K
rerankbooleanoptionalRerank
recall_evalbooleanoptionalRecall Eval
kindstringoptionalKind
Example request
{
  "instructions": "string",
  "description": "string",
  "max_distance": 0,
  "top_k": 0,
  "rerank": true,
  "recall_eval": true,
  "kind": "string"
}
Response · 200 · KbOut
namestringrequiredName
kindstringoptionalKind
instructionsstringrequiredInstructions
descriptionstringrequiredDescription
max_distancenumber?requiredMax Distance
top_kinteger?optionalTop K
rerankbooleanoptionalRerank
recall_evalbooleanoptionalRecall Eval
documentsintegeroptionalDocuments
chunksintegeroptionalChunks
chunk_spreadinteger[]?optionalChunk Spread
edited_chunksintegeroptionalEdited Chunks
Example response
{
  "name": "string",
  "kind": "string",
  "instructions": "string",
  "description": "string",
  "max_distance": 0,
  "top_k": 0,
  "rerank": true,
  "recall_eval": true,
  "documents": 0,
  "chunks": 0,
  "chunk_spread": [
    0
  ],
  "edited_chunks": 0
}
GET/knowledge-bases/{name}/chunks/{chunk_id}

Get Kb Chunk

Parameters
namepathstringrequired
chunk_idpathstringrequired
Response · 200 · KbChunkOut
idstringrequiredId
contentstringrequiredContent
index_textstring?optionalIndex Text
doc_idstring?optionalDoc Id
doc_titlestring?optionalDoc Title
sourcestring?optionalSource
edited_atstring?optionalEdited At
Example response
{
  "id": "string",
  "content": "string",
  "index_text": "string",
  "doc_id": "string",
  "doc_title": "string",
  "source": "string",
  "edited_at": "string"
}
PATCH/knowledge-bases/{name}/chunks/{chunk_id}

Edit Kb Chunk

Parameters
namepathstringrequired
chunk_idpathstringrequired
Request body · JSON
contentstring?optionalContent
index_textstring?optionalIndex Text
Example request
{
  "content": "string",
  "index_text": "string"
}
Response · 200 · KbChunkOut
idstringrequiredId
contentstringrequiredContent
index_textstring?optionalIndex Text
doc_idstring?optionalDoc Id
doc_titlestring?optionalDoc Title
sourcestring?optionalSource
edited_atstring?optionalEdited At
Example response
{
  "id": "string",
  "content": "string",
  "index_text": "string",
  "doc_id": "string",
  "doc_title": "string",
  "source": "string",
  "edited_at": "string"
}
POST/knowledge-bases/{name}/chunks/search

Search Kb Chunks

Parameters
namepathstringrequired
Request body · JSON
chunk_idstring?optionalChunk Id
sourcestring?optionalSource
textstring?optionalText
limitintegeroptionalLimit
edited_onlybooleanoptionalEdited Only
Example request
{
  "chunk_id": "string",
  "source": "string",
  "text": "string",
  "limit": 0,
  "edited_only": true
}
Response · 200 · KbChunkOut[]
idstringrequiredId
contentstringrequiredContent
index_textstring?optionalIndex Text
doc_idstring?optionalDoc Id
doc_titlestring?optionalDoc Title
sourcestring?optionalSource
edited_atstring?optionalEdited At
Example response
[
  {
    "id": "string",
    "content": "string",
    "index_text": "string",
    "doc_id": "string",
    "doc_title": "string",
    "source": "string",
    "edited_at": "string"
  }
]
GET/knowledge-bases/{name}/documents

List documents (optionally ?tag=).

Parameters
namepathstringrequired
tagquerystring?optional
Response · 200 · KbDocOut[]
idstringrequiredId
titlestringrequiredTitle
sourcestring?requiredSource
tagsstring[]optionalTags
chunksintegeroptionalChunks
Example response
[
  {
    "id": "string",
    "title": "string",
    "source": "string",
    "tags": [
      "string"
    ],
    "chunks": 0
  }
]
POST/knowledge-bases/{name}/documents

Add a text document (chunked + embedded synchronously).

Parameters
namepathstringrequired
Request body · JSON
titlestringrequiredTitle
contentstringrequiredContent
sourcestring?optionalSource
no_chunkbooleanoptionalNo Chunk
Example request
{
  "title": "string",
  "content": "string",
  "source": "string",
  "no_chunk": true
}
Response · 200 · KbIngestOut
document_idstringrequiredDocument Id
chunksintegerrequiredChunks
importedintegeroptionalImported
chunked_anywaystring[]optionalChunked Anyway
Example response
{
  "document_id": "string",
  "chunks": 0,
  "imported": 0,
  "chunked_anyway": [
    "string"
  ]
}
DELETE/knowledge-bases/{name}/documents/{doc_id}

Delete a document (and its chunks).

Parameters
namepathstringrequired
doc_idpathstringrequired

Response 204 — No Content (success, empty body).

GET/knowledge-bases/{name}/documents/{doc_id}/chunks

List Document Chunks

Parameters
namepathstringrequired
doc_idpathstringrequired
Response · 200 · KbChunkOut[]
idstringrequiredId
contentstringrequiredContent
index_textstring?optionalIndex Text
doc_idstring?optionalDoc Id
doc_titlestring?optionalDoc Title
sourcestring?optionalSource
edited_atstring?optionalEdited At
Example response
[
  {
    "id": "string",
    "content": "string",
    "index_text": "string",
    "doc_id": "string",
    "doc_title": "string",
    "source": "string",
    "edited_at": "string"
  }
]
PATCH/knowledge-bases/{name}/documents/{doc_id}/tags

Set a document's organisation tags.

Parameters
namepathstringrequired
doc_idpathstringrequired
Request body · JSON
tagsstring[]requiredTags
Example request
{
  "tags": [
    "string"
  ]
}
Response · 200 · KbDocOut
idstringrequiredId
titlestringrequiredTitle
sourcestring?requiredSource
tagsstring[]optionalTags
chunksintegeroptionalChunks
Example response
{
  "id": "string",
  "title": "string",
  "source": "string",
  "tags": [
    "string"
  ],
  "chunks": 0
}
POST/knowledge-bases/{name}/documents/inspect

Inspect Upload

Parameters
namepathstringrequired
Request body · multipart/form-data
filestringrequiredFile
Example request
{
  "file": "string"
}

Response 200 · object — unstructured JSON (no fixed schema).

POST/knowledge-bases/{name}/documents/upload

Upload a file (pdf/docx/md/html/txt) or a zip of a folder — subfolders are walked.

Parameters
namepathstringrequired
Request body · multipart/form-data
filestringrequiredFile
titlestring?optionalTitle
no_chunkbooleanoptionalNo Chunk
Example request
{
  "file": "string",
  "title": "string",
  "no_chunk": true
}
Response · 200 · KbIngestOut
document_idstringrequiredDocument Id
chunksintegerrequiredChunks
importedintegeroptionalImported
chunked_anywaystring[]optionalChunked Anyway
Example response
{
  "document_id": "string",
  "chunks": 0,
  "imported": 0,
  "chunked_anyway": [
    "string"
  ]
}
curl -X POST "https://api.agent4.io/v1/knowledge-bases/company-policy/documents/upload" \
  -H "X-API-Key: $KEY" -F "file=@/path/to/policy.pdf"
POST/knowledge-bases/{name}/documents/upload/stream

Upload Kb Archive Stream

Parameters
namepathstringrequired
Request body · multipart/form-data
filestringrequiredFile
no_chunkbooleanoptionalNo Chunk
Example request
{
  "file": "string",
  "no_chunk": true
}

Response 200 · any

Example response
"…"
GET/knowledge-bases/{name}/index

Get Kb Index

Parameters
namepathstringrequired

Response 200 · object — unstructured JSON (no fixed schema).

POST/knowledge-bases/{name}/index/build

Build Kb Index

Parameters
namepathstringrequired

Response 200 · object — unstructured JSON (no fixed schema).

POST/knowledge-bases/{name}/index/schema

Patch Kb Index Schema

Parameters
namepathstringrequired
Request body · JSON
requeststringrequiredRequest
applybooleanoptionalApply
Example request
{
  "request": "string",
  "apply": true
}

Response 200 · object — unstructured JSON (no fixed schema).

GET/knowledge-bases/{name}/products

List catalog products (kind=catalog KB).

Parameters
namepathstringrequired
Response · 200 · ProductOut[]
idstringrequiredId
namestringrequiredName
descriptionstringrequiredDescription
pricestring?requiredPrice
availabilitystring?requiredAvailability
categorystring?requiredCategory
tagsstring[]requiredTags
image_urlstring?requiredImage Url
image_urlsstring[]requiredImage Urls
linkstring?requiredLink
sourcestringrequiredSource
Example response
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "price": "string",
    "availability": "string",
    "category": "string",
    "tags": [
      "string"
    ],
    "image_url": "string",
    "image_urls": [
      "string"
    ],
    "link": "string",
    "source": "string"
  }
]
POST/knowledge-bases/{name}/products

Add a product to a catalog KB.

Parameters
namepathstringrequired
Request body · JSON
namestringrequiredName
descriptionstringoptionalDescription
pricestring?optionalPrice
availabilitystring?optionalAvailability
categorystring?optionalCategory
tagsstring[]optionalTags
image_urlstring?optionalImage Url
image_urlsstring[]optionalImage Urls
linkstring?optionalLink
Example request
{
  "name": "string",
  "description": "string",
  "price": "string",
  "availability": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "image_url": "string",
  "image_urls": [
    "string"
  ],
  "link": "string"
}
Response · 200 · ProductOut
idstringrequiredId
namestringrequiredName
descriptionstringrequiredDescription
pricestring?requiredPrice
availabilitystring?requiredAvailability
categorystring?requiredCategory
tagsstring[]requiredTags
image_urlstring?requiredImage Url
image_urlsstring[]requiredImage Urls
linkstring?requiredLink
sourcestringrequiredSource
Example response
{
  "id": "string",
  "name": "string",
  "description": "string",
  "price": "string",
  "availability": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "image_url": "string",
  "image_urls": [
    "string"
  ],
  "link": "string",
  "source": "string"
}
DELETE/knowledge-bases/{name}/products/{product_id}

Delete a product.

Parameters
namepathstringrequired
product_idpathstringrequired

Response 204 — No Content (success, empty body).

PUT/knowledge-bases/{name}/products/{product_id}

Update a product.

Parameters
namepathstringrequired
product_idpathstringrequired
Request body · JSON
namestringrequiredName
descriptionstringoptionalDescription
pricestring?optionalPrice
availabilitystring?optionalAvailability
categorystring?optionalCategory
tagsstring[]optionalTags
image_urlstring?optionalImage Url
image_urlsstring[]optionalImage Urls
linkstring?optionalLink
Example request
{
  "name": "string",
  "description": "string",
  "price": "string",
  "availability": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "image_url": "string",
  "image_urls": [
    "string"
  ],
  "link": "string"
}
Response · 200 · ProductOut
idstringrequiredId
namestringrequiredName
descriptionstringrequiredDescription
pricestring?requiredPrice
availabilitystring?requiredAvailability
categorystring?requiredCategory
tagsstring[]requiredTags
image_urlstring?requiredImage Url
image_urlsstring[]requiredImage Urls
linkstring?requiredLink
sourcestringrequiredSource
Example response
{
  "id": "string",
  "name": "string",
  "description": "string",
  "price": "string",
  "availability": "string",
  "category": "string",
  "tags": [
    "string"
  ],
  "image_url": "string",
  "image_urls": [
    "string"
  ],
  "link": "string",
  "source": "string"
}
POST/knowledge-bases/{name}/products/import

Bulk-import products.

Parameters
namepathstringrequired
Request body · multipart/form-data
urlstring?optionalUrl
filestring?optionalFile
Example request
{
  "url": "string",
  "file": "string"
}

Response 200 · object — unstructured JSON (no fixed schema).

POST/knowledge-bases/{name}/purge

Purge Kb

Parameters
namepathstringrequired
Request body · JSON
confirm_namestringrequiredConfirm Name
Example request
{
  "confirm_name": "string"
}

Response 200 · object — unstructured JSON (no fixed schema).

POST/knowledge-bases/{name}/search

Search — the same retrieval a live chat uses; verify a real question retrieves before relying on it.

Parameters
namepathstringrequired
Request body · JSON
querystringrequiredQuery
kinteger?optionalK
Example request
{
  "query": "string",
  "k": 0
}
Response · 200 · KbSearchHit[]
kbstringrequiredKb
contentstringrequiredContent
distancenumberrequiredDistance
index_textstring?optionalIndex Text
Example response
[
  {
    "kb": "string",
    "content": "string",
    "distance": 0,
    "index_text": "string"
  }
]
curl -X POST "https://api.agent4.io/v1/knowledge-bases/company-policy/search" -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"query":"late fee"}'
POST/manage/knowledge-bases/{name}/crawl

Start crawling a website into the KB (discovery only; no tokens spent yet).

Parameters
namepathstringrequired
Request body · JSON
urlstringrequiredUrl
path_prefixstring?optionalPath Prefix
max_depthintegeroptionalMax Depth
max_pagesintegeroptionalMax Pages
Example request
{
  "url": "string",
  "path_prefix": "string",
  "max_depth": 0,
  "max_pages": 0
}
Response · 201 · CrawlOut
idstringrequiredId
knowledge_basestringrequiredKnowledge Base
start_urlstringrequiredStart Url
statusstringrequiredStatus
error_codestring?requiredError Code
errorstring?requiredError
discoveredintegerrequiredDiscovered
fetchedintegerrequiredFetched
embeddedintegerrequiredEmbedded
skippedintegerrequiredSkipped
flaggedintegerrequiredFlagged
total_charsintegerrequiredTotal Chars
estimated_tokensintegerrequiredEstimated Tokens
tokens_usedintegerrequiredTokens Used
created_atstringrequiredCreated At
finished_atstring?requiredFinished At
Example response
{
  "id": "string",
  "knowledge_base": "string",
  "start_url": "string",
  "status": "string",
  "error_code": "string",
  "error": "string",
  "discovered": 0,
  "fetched": 0,
  "embedded": 0,
  "skipped": 0,
  "flagged": 0,
  "total_chars": 0,
  "estimated_tokens": 0,
  "tokens_used": 0,
  "created_at": "string",
  "finished_at": "string"
}
GET/manage/knowledge-bases/{name}/graph

3D projection (knowledge starmap) of the KB's chunks.

Parameters
namepathstringrequired
limitqueryinteger?optional
refreshquerybooleanoptional
qquerystringoptional
streamquerybooleanoptional

Response 200 · object — unstructured JSON (no fixed schema).

Skills

Load-on-demand procedures. description says WHEN (one line, in the prompt every turn); instructions is the full guide (fetched only when the skill loads).

GET/skills

List skills.

Response · 200 · SkillOut[]
namestringrequiredName
descriptionstringrequiredDescription
instructionsstringrequiredInstructions
toolsstring[]requiredTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
warningsobject[]optionalWarnings
Example response
[
  {
    "name": "string",
    "description": "string",
    "instructions": "string",
    "tools": [
      "string"
    ],
    "knowledge_bases": [
      "string"
    ],
    "model": "string",
    "menu_label": "string",
    "menu_prompt": "string",
    "menu_anchors": "string",
    "warnings": [
      {}
    ]
  }
]
DELETE/skills/{name}

Delete a skill.

Parameters
namepathstringrequired

Response 204 — No Content (success, empty body).

GET/skills/{name}

Get a skill (with full instructions).

Parameters
namepathstringrequired
Response · 200 · SkillOut
namestringrequiredName
descriptionstringrequiredDescription
instructionsstringrequiredInstructions
toolsstring[]requiredTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
warningsobject[]optionalWarnings
Example response
{
  "name": "string",
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string",
  "warnings": [
    {}
  ]
}
PATCH/skills/{name}

Partial update (404 if it does not exist).

Parameters
namepathstringrequired
Request body · JSON
descriptionstring?optionalDescription
instructionsstring?optionalInstructions
toolsstring[]?optionalTools
tools_addstring[]?optionalTools Add
tools_removestring[]?optionalTools Remove
knowledge_basesstring[]?optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
Example request
{
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "tools_add": [
    "string"
  ],
  "tools_remove": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string"
}
Response · 200 · SkillOut
namestringrequiredName
descriptionstringrequiredDescription
instructionsstringrequiredInstructions
toolsstring[]requiredTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
warningsobject[]optionalWarnings
Example response
{
  "name": "string",
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string",
  "warnings": [
    {}
  ]
}
POST/skills/{name}

Create a skill.

Parameters
namepathstringrequired
Request body · JSON
descriptionstringoptionalDescription
instructionsstringoptionalInstructions
toolsstring[]optionalTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
Example request
{
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string"
}
Response · 201 · SkillOut
namestringrequiredName
descriptionstringrequiredDescription
instructionsstringrequiredInstructions
toolsstring[]requiredTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
warningsobject[]optionalWarnings
Example response
{
  "name": "string",
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string",
  "warnings": [
    {}
  ]
}
curl -X POST https://api.agent4.io/v1/skills/booking -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"description":"Use when the visitor wants to book.","instructions":"Collect party size, date+time, duration; never confirm the slot."}'
PUT/skills/{name}

Replace a skill.

Parameters
namepathstringrequired
Request body · JSON
descriptionstringoptionalDescription
instructionsstringoptionalInstructions
toolsstring[]optionalTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
Example request
{
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string"
}
Response · 200 · SkillOut
namestringrequiredName
descriptionstringrequiredDescription
instructionsstringrequiredInstructions
toolsstring[]requiredTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
warningsobject[]optionalWarnings
Example response
{
  "name": "string",
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string",
  "warnings": [
    {}
  ]
}
GET/skills/{name}/revisions

Skill revision history.

Parameters
namepathstringrequired
Response · 200 · SkillRevisionOut[]
idstringrequiredId
created_atstringrequiredCreated At
actorstring?optionalActor
snapshotobjectrequiredSnapshot
Example response
[
  {
    "id": "string",
    "created_at": "string",
    "actor": "string",
    "snapshot": {}
  }
]
POST/skills/{name}/revisions/{rev_id}/restore

Restore a skill revision.

Parameters
namepathstringrequired
rev_idpathstringrequired
Response · 200 · SkillOut
namestringrequiredName
descriptionstringrequiredDescription
instructionsstringrequiredInstructions
toolsstring[]requiredTools
knowledge_basesstring[]optionalKnowledge Bases
modelstring?optionalModel
menu_labelstring?optionalMenu Label
menu_promptstring?optionalMenu Prompt
menu_anchorsstring?optionalMenu Anchors
warningsobject[]optionalWarnings
Example response
{
  "name": "string",
  "description": "string",
  "instructions": "string",
  "tools": [
    "string"
  ],
  "knowledge_bases": [
    "string"
  ],
  "model": "string",
  "menu_label": "string",
  "menu_prompt": "string",
  "menu_anchors": "string",
  "warnings": [
    {}
  ]
}

Storylines

Multi-step, stateful, guided flows (a graph of nodes with conditional exits). See the cookbook for the graph shape.

GET/storylines

List storylines (optionally ?agent=).

Parameters
agentquerystring?optional
Response · 200 · StorylineOut[]
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
[
  {
    "id": "string",
    "agent_name": "string",
    "key": "string",
    "name": "string",
    "description": "string",
    "graph": {},
    "profile_schema": {},
    "status": "string",
    "published_revision_id": "string",
    "is_default": true,
    "user_visibility": "string",
    "entry": "string",
    "display_name": "string",
    "allow_exit": true,
    "show_profile": true,
    "on_complete": "string",
    "allow_agent_enroll": true,
    "enroll_trigger": "string",
    "concurrency": "string",
    "next_storyline_id": "string",
    "position": 0,
    "version": 0,
    "updated_at": "string"
  }
]
POST/storylines

Create a Storyline draft.

Request body · JSON
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringoptionalName
descriptionstringoptionalDescription
graphobjectoptionalGraph
profile_schemaobjectoptionalProfile Schema
is_defaultbooleanoptionalIs Default
user_visibilitystringoptionalUser Visibility
learner_visibilitystring?optionalLearner Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringoptionalOn Complete
allow_agent_enrollbooleanoptionalAllow Agent Enroll
enroll_triggerstringoptionalEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?optionalNext Storyline Id
positionintegeroptionalPosition
expected_versioninteger?optionalExpected Version
Example request
{
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "is_default": true,
  "user_visibility": "string",
  "learner_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "expected_version": 0
}
Response · 201 · StorylineOut
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "status": "string",
  "published_revision_id": "string",
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "version": 0,
  "updated_at": "string"
}
DELETE/storylines/{storyline_id}

Delete Storyline

Parameters
storyline_idpathstringrequired

Response 204 — No Content (success, empty body).

GET/storylines/{storyline_id}

Get Storyline

Parameters
storyline_idpathstringrequired
Response · 200 · StorylineOut
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "status": "string",
  "published_revision_id": "string",
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "version": 0,
  "updated_at": "string"
}
PUT/storylines/{storyline_id}

Update Storyline

Parameters
storyline_idpathstringrequired
Request body · JSON
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringoptionalName
descriptionstringoptionalDescription
graphobjectoptionalGraph
profile_schemaobjectoptionalProfile Schema
is_defaultbooleanoptionalIs Default
user_visibilitystringoptionalUser Visibility
learner_visibilitystring?optionalLearner Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringoptionalOn Complete
allow_agent_enrollbooleanoptionalAllow Agent Enroll
enroll_triggerstringoptionalEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?optionalNext Storyline Id
positionintegeroptionalPosition
expected_versioninteger?optionalExpected Version
Example request
{
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "is_default": true,
  "user_visibility": "string",
  "learner_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "expected_version": 0
}
Response · 200 · StorylineOut
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "status": "string",
  "published_revision_id": "string",
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "version": 0,
  "updated_at": "string"
}
POST/storylines/{storyline_id}/clone

Clone Storyline

Parameters
storyline_idpathstringrequired
Response · 201 · StorylineOut
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "status": "string",
  "published_revision_id": "string",
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "version": 0,
  "updated_at": "string"
}
GET/storylines/{storyline_id}/enrollments

List Enrollments

Parameters
storyline_idpathstringrequired
Response · 200 · EnrollmentOut[]
idstringrequiredId
user_idstringrequiredUser Id
current_node_keystringrequiredCurrent Node Key
statusstringrequiredStatus
entered_node_atstringrequiredEntered Node At
updated_atstringrequiredUpdated At
Example response
[
  {
    "id": "string",
    "user_id": "string",
    "current_node_key": "string",
    "status": "string",
    "entered_node_at": "string",
    "updated_at": "string"
  }
]
POST/storylines/{storyline_id}/enrollments/migrate

Migrate Enrollments

Parameters
storyline_idpathstringrequired
Request body · JSON
actionstringrequiredAction
from_nodestring?optionalFrom Node
to_nodestring?optionalTo Node
Example request
{
  "action": "string",
  "from_node": "string",
  "to_node": "string"
}

Response 200 · object — unstructured JSON (no fixed schema).

GET/storylines/{storyline_id}/export

Export Storyline

Parameters
storyline_idpathstringrequired
Response · 200 · StorylineExport
schema_versionintegerrequiredSchema Version
kindstringoptionalKind
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
agent_namestringrequiredAgent Name
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
Example response
{
  "schema_version": 0,
  "kind": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "agent_name": "string",
  "graph": {},
  "profile_schema": {},
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string"
}
GET/storylines/{storyline_id}/funnel

Storyline Funnel

Parameters
storyline_idpathstringrequired
Response · 200 · FunnelOut
nodesobjectrequiredNodes
Example response
{
  "nodes": {}
}
POST/storylines/{storyline_id}/publish

Publish Storyline

Parameters
storyline_idpathstringrequired
Response · 200 · StorylineOut
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "status": "string",
  "published_revision_id": "string",
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "version": 0,
  "updated_at": "string"
}
GET/storylines/{storyline_id}/revisions

List Revisions

Parameters
storyline_idpathstringrequired
Response · 200 · app__api__storylines__RevisionOut[]
idstringrequiredId
versionintegerrequiredVersion
actorstring?requiredActor
created_atstringrequiredCreated At
Example response
[
  {
    "id": "string",
    "version": 0,
    "actor": "string",
    "created_at": "string"
  }
]
POST/storylines/{storyline_id}/unpublish

Unpublish Storyline

Parameters
storyline_idpathstringrequired
Response · 200 · StorylineOut
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "status": "string",
  "published_revision_id": "string",
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "version": 0,
  "updated_at": "string"
}
POST/storylines/{storyline_id}/validate

Validate Storyline

Parameters
storyline_idpathstringrequired
Response · 200 · ValidationOut
okbooleanrequiredOk
errorsobject[]requiredErrors
Example response
{
  "ok": true,
  "errors": [
    {}
  ]
}
GET/storylines/feature

Storyline Feature

Response 200 · object — unstructured JSON (no fixed schema).

POST/storylines/import

Import a Storyline JSON as a draft.

Request body · JSON
schema_versionintegeroptionalSchema Version
keystringoptionalKey
namestringoptionalName
descriptionstringoptionalDescription
agent_namestringoptionalAgent Name
graphobjectoptionalGraph
profile_schemaobjectoptionalProfile Schema
user_visibilitystringoptionalUser Visibility
learner_visibilitystring?optionalLearner Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringoptionalOn Complete
allow_agent_enrollbooleanoptionalAllow Agent Enroll
enroll_triggerstringoptionalEnroll Trigger
override_agent_namestring?optionalOverride Agent Name
Example request
{
  "schema_version": 0,
  "key": "string",
  "name": "string",
  "description": "string",
  "agent_name": "string",
  "graph": {},
  "profile_schema": {},
  "user_visibility": "string",
  "learner_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "override_agent_name": "string"
}
Response · 201 · StorylineOut
idstringrequiredId
agent_namestringrequiredAgent Name
keystringrequiredKey
namestringrequiredName
descriptionstringrequiredDescription
graphobjectrequiredGraph
profile_schemaobjectrequiredProfile Schema
statusstringrequiredStatus
published_revision_idstring?requiredPublished Revision Id
is_defaultbooleanrequiredIs Default
user_visibilitystringrequiredUser Visibility
entrystringoptionalEntry
display_namestringoptionalDisplay Name
allow_exitbooleanoptionalAllow Exit
show_profilebooleanoptionalShow Profile
on_completestringrequiredOn Complete
allow_agent_enrollbooleanrequiredAllow Agent Enroll
enroll_triggerstringrequiredEnroll Trigger
concurrencystringoptionalConcurrency
next_storyline_idstring?requiredNext Storyline Id
positionintegerrequiredPosition
versionintegerrequiredVersion
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "graph": {},
  "profile_schema": {},
  "status": "string",
  "published_revision_id": "string",
  "is_default": true,
  "user_visibility": "string",
  "entry": "string",
  "display_name": "string",
  "allow_exit": true,
  "show_profile": true,
  "on_complete": "string",
  "allow_agent_enroll": true,
  "enroll_trigger": "string",
  "concurrency": "string",
  "next_storyline_id": "string",
  "position": 0,
  "version": 0,
  "updated_at": "string"
}

Your MCP servers & tools

Bring your own tools: register a remote MCP server, then attach its tools to an agent.

GET/mcp-servers

List the MCP servers registered on your tenant (no secrets).

Response · 200 · McpServerOut[]
idstringrequiredId
namestringrequiredName
transportstringrequiredTransport
enabledbooleanrequiredEnabled
configobjectrequiredConfig
statusstring?optionalStatus
last_errorstring?optionalLast Error
discovered_toolsany[]?optionalDiscovered Tools
last_checked_atstring?optionalLast Checked At
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
[
  {
    "id": "string",
    "name": "string",
    "transport": "string",
    "enabled": true,
    "config": {},
    "status": "string",
    "last_error": "string",
    "discovered_tools": [
      "…"
    ],
    "last_checked_at": "string",
    "created_at": "string",
    "updated_at": "string"
  }
]
POST/mcp-servers

Register a remote MCP server (transport: streamable_http | sse; stdio is rejected).

Request body · JSON
namestringrequiredName
transportstringoptionalTransport
configobjectoptionalConfig
enabledbooleanoptionalEnabled
Example request
{
  "name": "string",
  "transport": "string",
  "config": {},
  "enabled": true
}
Response · 201 · McpServerOut
idstringrequiredId
namestringrequiredName
transportstringrequiredTransport
enabledbooleanrequiredEnabled
configobjectrequiredConfig
statusstring?optionalStatus
last_errorstring?optionalLast Error
discovered_toolsany[]?optionalDiscovered Tools
last_checked_atstring?optionalLast Checked At
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "transport": "string",
  "enabled": true,
  "config": {},
  "status": "string",
  "last_error": "string",
  "discovered_tools": [
    "…"
  ],
  "last_checked_at": "string",
  "created_at": "string",
  "updated_at": "string"
}
curl -X POST https://api.agent4.io/v1/mcp-servers -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"my-tools","transport":"streamable_http","config":{"url":"https://tools.example.com/mcp"}}'
DELETE/mcp-servers/{sid}

Delete Server

Parameters
sidpathstringrequired

Response 204 — No Content (success, empty body).

PATCH/mcp-servers/{sid}

Update Server

Parameters
sidpathstringrequired
Request body · JSON
namestring?optionalName
transportstring?optionalTransport
configobject?optionalConfig
enabledboolean?optionalEnabled
Example request
{
  "name": "string",
  "transport": "string",
  "config": {},
  "enabled": true
}
Response · 200 · McpServerOut
idstringrequiredId
namestringrequiredName
transportstringrequiredTransport
enabledbooleanrequiredEnabled
configobjectrequiredConfig
statusstring?optionalStatus
last_errorstring?optionalLast Error
discovered_toolsany[]?optionalDiscovered Tools
last_checked_atstring?optionalLast Checked At
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "transport": "string",
  "enabled": true,
  "config": {},
  "status": "string",
  "last_error": "string",
  "discovered_tools": [
    "…"
  ],
  "last_checked_at": "string",
  "created_at": "string",
  "updated_at": "string"
}
POST/mcp-servers/{sid}/probe

Probe Server

Parameters
sidpathstringrequired
Request body · JSON
instructionstringrequiredInstruction
toolstring?optionalTool
executebooleanoptionalExecute
Example request
{
  "instruction": "string",
  "tool": "string",
  "execute": true
}
Response · 200 · ProbeOut
calledbooleanrequiredCalled
toolstring?optionalTool
argumentsobject?optionalArguments
executedbooleanoptionalExecuted
resultstring?optionalResult
replystring?optionalReply
errorstring?optionalError
Example response
{
  "called": true,
  "tool": "string",
  "arguments": {},
  "executed": true,
  "result": "string",
  "reply": "string",
  "error": "string"
}
GET/mcp-servers/{sid}/reveal

Reveal Config

Parameters
sidpathstringrequired
Response · 200 · RevealOut
configobjectrequiredConfig
Example response
{
  "config": {}
}
POST/mcp-servers/{sid}/test

Test Server

Parameters
sidpathstringrequired
Response · 200 · McpServerOut
idstringrequiredId
namestringrequiredName
transportstringrequiredTransport
enabledbooleanrequiredEnabled
configobjectrequiredConfig
statusstring?optionalStatus
last_errorstring?optionalLast Error
discovered_toolsany[]?optionalDiscovered Tools
last_checked_atstring?optionalLast Checked At
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "transport": "string",
  "enabled": true,
  "config": {},
  "status": "string",
  "last_error": "string",
  "discovered_tools": [
    "…"
  ],
  "last_checked_at": "string",
  "created_at": "string",
  "updated_at": "string"
}
POST/mcp-servers/test-config

Probe a transport+config before saving (connect once, don't persist).

Request body · JSON
transportstringoptionalTransport
configobjectoptionalConfig
Example request
{
  "transport": "string",
  "config": {}
}
Response · 200 · McpServerOut
idstringrequiredId
namestringrequiredName
transportstringrequiredTransport
enabledbooleanrequiredEnabled
configobjectrequiredConfig
statusstring?optionalStatus
last_errorstring?optionalLast Error
discovered_toolsany[]?optionalDiscovered Tools
last_checked_atstring?optionalLast Checked At
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "transport": "string",
  "enabled": true,
  "config": {},
  "status": "string",
  "last_error": "string",
  "discovered_tools": [
    "…"
  ],
  "last_checked_at": "string",
  "created_at": "string",
  "updated_at": "string"
}

Page playbooks

A per-page briefing (background, opener, suggested questions) chosen from the visitor's URL. Match rules are globs.

GET/manage/page-context-stats

Opens and suggested-question clicks per playbook.

Parameters
daysqueryintegeroptional
Response · 200 · PlaybookStat[]
keystringrequiredKey
openedintegeroptionalOpened
question_clicksintegeroptionalQuestion Clicks
per_questionobjectoptionalPer Question
Example response
[
  {
    "key": "string",
    "opened": 0,
    "question_clicks": 0,
    "per_question": {}
  }
]
GET/manage/page-context-templates

Starter templates by page type.

Parameters
langquerystringoptional
Response · 200 · PlaybookTemplate[]
keystringrequiredKey
labelstringrequiredLabel
context_hintstringrequiredContext Hint
questionsstring[]requiredQuestions
Example response
[
  {
    "key": "string",
    "label": "string",
    "context_hint": "string",
    "questions": [
      "string"
    ]
  }
]
GET/manage/page-contexts

List page playbooks (match rules, greeting mode, position).

Response · 200 · PageContextOut[]
labelstringoptionalLabel
url_patternstring?optionalUrl Pattern
contextstringoptionalContext
greetingstring?optionalGreeting
questionsstring[]?optionalQuestions
greeting_modestringoptionalGreeting Mode
is_defaultbooleanoptionalIs Default
positionintegeroptionalPosition
keystringrequiredKey
generated_langsstring[]optionalGenerated Langs
Example response
[
  {
    "label": "string",
    "url_pattern": "string",
    "context": "string",
    "greeting": "string",
    "questions": [
      "string"
    ],
    "greeting_mode": "string",
    "is_default": true,
    "position": 0,
    "key": "string",
    "generated_langs": [
      "string"
    ]
  }
]
DELETE/manage/page-contexts/{key}

Delete a playbook.

Parameters
keypathstringrequired

Response 204 — No Content (success, empty body).

PUT/manage/page-contexts/{key}

Create or replace a playbook (full-replace).

Parameters
keypathstringrequired
Request body · JSON
labelstringoptionalLabel
url_patternstring?optionalUrl Pattern
contextstringoptionalContext
greetingstring?optionalGreeting
questionsstring[]?optionalQuestions
greeting_modestringoptionalGreeting Mode
is_defaultbooleanoptionalIs Default
positionintegeroptionalPosition
Example request
{
  "label": "string",
  "url_pattern": "string",
  "context": "string",
  "greeting": "string",
  "questions": [
    "string"
  ],
  "greeting_mode": "string",
  "is_default": true,
  "position": 0
}
Response · 200 · PageContextOut
labelstringoptionalLabel
url_patternstring?optionalUrl Pattern
contextstringoptionalContext
greetingstring?optionalGreeting
questionsstring[]?optionalQuestions
greeting_modestringoptionalGreeting Mode
is_defaultbooleanoptionalIs Default
positionintegeroptionalPosition
keystringrequiredKey
generated_langsstring[]optionalGenerated Langs
Example response
{
  "label": "string",
  "url_pattern": "string",
  "context": "string",
  "greeting": "string",
  "questions": [
    "string"
  ],
  "greeting_mode": "string",
  "is_default": true,
  "position": 0,
  "key": "string",
  "generated_langs": [
    "string"
  ]
}
curl -X PUT https://api.agent4.io/v1/manage/page-contexts/pricing -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"label":"Pricing","url_pattern":"*/pricing","context":"Visitors compare plans.","greeting_mode":"generated"}'
GET/manage/page-contexts/resolve

Test which playbook a URL hits (?url= or ?key=).

Parameters
urlquerystring?optional
keyquerystring?optional
Response · 200 · ResolveOut
keystring?optionalKey
labelstringoptionalLabel
matched_bystringoptionalMatched By
Example response
{
  "key": "string",
  "label": "string",
  "matched_by": "string"
}

Long-document writing

A document type is a skeleton plus the information the agent must have before it writes. Publishing freezes a revision — a run in flight keeps the version it started with, so editing a type never renumbers a document someone is already reading. Visitors drive their own documents through the share API; this group is the tenant-side configuration and the operations board.

GET/manage/writing

Operations board: status, progress, how long a run has been stuck, and why it failed. Returns no document text — the body is encrypted per end user and this endpoint has no key for it.

Parameters
limitqueryintegeroptional
Response · 200 · Board
by_statusobjectrequiredBy Status
active_jobsintegeroptionalActive Jobs
stale_jobsintegeroptionalStale Jobs
stuckintegeroptionalStuck
waitingintegeroptionalWaiting
runsRunRow[]requiredRuns
Example response
{
  "by_status": {},
  "active_jobs": 0,
  "stale_jobs": 0,
  "stuck": 0,
  "waiting": 0,
  "runs": [
    {}
  ]
}
GET/writing-types

List your document types with how many documents each has produced.

Response · 200 · TypeOut[]
idstringrequiredId
namestringrequiredName
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
statusstringoptionalStatus
versionintegeroptionalVersion
runsintegeroptionalRuns
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
[
  {
    "id": "string",
    "name": "string",
    "display_name": "string",
    "description": "string",
    "agent_name": "string",
    "outline": [
      {}
    ],
    "info_schema": {},
    "boundary": "string",
    "knowledge_bases": [
      "string"
    ],
    "match_hints": "string",
    "status": "string",
    "version": 0,
    "runs": 0,
    "created_at": "string",
    "updated_at": "string"
  }
]
DELETE/writing-types/{name}

Delete a type. Documents already written from it are unaffected — they keep their own frozen copy.

Parameters
namepathstringrequired

Response 204 — No Content (success, empty body).

GET/writing-types/{name}

Get one type: skeleton, required information, writing boundary.

Parameters
namepathstringrequired
Response · 200 · TypeOut
idstringrequiredId
namestringrequiredName
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
statusstringoptionalStatus
versionintegeroptionalVersion
runsintegeroptionalRuns
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string",
  "status": "string",
  "version": 0,
  "runs": 0,
  "created_at": "string",
  "updated_at": "string"
}
PATCH/writing-types/{name}

Partial update. Validation runs on the merged result, so a patch that only changes `needs` is still checked against the stored `info_schema`.

Parameters
namepathstringrequired
Request body · JSON
display_namestring?optionalDisplay Name
descriptionstring?optionalDescription
agent_namestring?optionalAgent Name
outlineobject[]?optionalOutline
info_schemaobject?optionalInfo Schema
boundarystring?optionalBoundary
knowledge_basesstring[]?optionalKnowledge Bases
match_hintsstring?optionalMatch Hints
Example request
{
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string"
}
Response · 200 · TypeOut
idstringrequiredId
namestringrequiredName
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
statusstringoptionalStatus
versionintegeroptionalVersion
runsintegeroptionalRuns
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string",
  "status": "string",
  "version": 0,
  "runs": 0,
  "created_at": "string",
  "updated_at": "string"
}
POST/writing-types/{name}

Create a document type (409 if it exists). Validated on write: every `needs` key must exist in `info_schema`, field types must be text/number/date, section keys must be unique.

Parameters
namepathstringrequired
Request body · JSON
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
Example request
{
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string"
}
Response · 201 · TypeOut
idstringrequiredId
namestringrequiredName
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
statusstringoptionalStatus
versionintegeroptionalVersion
runsintegeroptionalRuns
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string",
  "status": "string",
  "version": 0,
  "runs": 0,
  "created_at": "string",
  "updated_at": "string"
}
curl -X POST https://api.agent4.io/v1/writing-types/reg-submission -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"display_name":"Regulatory submission","match_hints":"regulatory submission dossiers, technical files, CE or NMPA filings","boundary":"Never predict an approval outcome; never cite a regulation that is not yet in force.","info_schema":{"applicant_name":{"label":"Legal name of the applicant","type":"text","why":"It goes on the cover sheet; getting it wrong means refiling."}},"outline":[{"key":"applicant","title":"Applicant","requirements":"State the legal name, registered address and device class.","needs":["applicant_name"]}]}'
PUT/writing-types/{name}

Create or replace — full-replace semantics; a PUT without `outline` clears the skeleton.

Parameters
namepathstringrequired
Request body · JSON
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
Example request
{
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string"
}
Response · 200 · TypeOut
idstringrequiredId
namestringrequiredName
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
statusstringoptionalStatus
versionintegeroptionalVersion
runsintegeroptionalRuns
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string",
  "status": "string",
  "version": 0,
  "runs": 0,
  "created_at": "string",
  "updated_at": "string"
}
POST/writing-types/{name}/publish

Freeze a revision and compute the matching vector. Only published types are matched automatically; runs already in flight keep the revision they started with.

Parameters
namepathstringrequired
Response · 200 · TypeOut
idstringrequiredId
namestringrequiredName
display_namestringoptionalDisplay Name
descriptionstringoptionalDescription
agent_namestring?optionalAgent Name
outlineobject[]optionalOutline
info_schemaobjectoptionalInfo Schema
boundarystringoptionalBoundary
knowledge_basesstring[]optionalKnowledge Bases
match_hintsstringoptionalMatch Hints
statusstringoptionalStatus
versionintegeroptionalVersion
runsintegeroptionalRuns
created_atstringrequiredCreated At
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "name": "string",
  "display_name": "string",
  "description": "string",
  "agent_name": "string",
  "outline": [
    {}
  ],
  "info_schema": {},
  "boundary": "string",
  "knowledge_bases": [
    "string"
  ],
  "match_hints": "string",
  "status": "string",
  "version": 0,
  "runs": 0,
  "created_at": "string",
  "updated_at": "string"
}
GET/writing-types/{name}/revisions

Published revision history.

Parameters
namepathstringrequired
Response · 200 · app__api__writing_types__RevisionOut[]
idstringrequiredId
versionintegerrequiredVersion
sectionsintegerrequiredSections
actorstring?optionalActor
created_atstringrequiredCreated At
Example response
[
  {
    "id": "string",
    "version": 0,
    "sections": 0,
    "actor": "string",
    "created_at": "string"
  }
]

Scheduled tasks

GET/manage/scheduled-tasks

List scheduled / follow-up tasks (metadata; instruction decrypted where possible).

Parameters
statusquerystring?optional
limitqueryintegeroptional
cursorquerystring?optional
Response · 200 · ScheduledTaskPage
itemsScheduledTaskOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
POST/manage/scheduled-tasks/{task_id}/cancel

Cancel a pending task (409 if not pending).

Parameters
task_idpathstringrequired
Response · 200 · ScheduledTaskOut
idstringrequiredId
user_idstringrequiredUser Id
external_user_idstring?optionalExternal User Id
space_idstringrequiredSpace Id
space_namestring?optionalSpace Name
session_idstring?optionalSession Id
session_titlestring?optionalSession Title
agentstring?optionalAgent
channelstringrequiredChannel
kindstringoptionalKind
titlestring?optionalTitle
cronstring?optionalCron
statusstringrequiredStatus
instructionstring?optionalInstruction
run_atstringrequiredRun At
created_atstringrequiredCreated At
last_errorstring?optionalLast Error
Example response
{
  "id": "string",
  "user_id": "string",
  "external_user_id": "string",
  "space_id": "string",
  "space_name": "string",
  "session_id": "string",
  "session_title": "string",
  "agent": "string",
  "channel": "string",
  "kind": "string",
  "title": "string",
  "cron": "string",
  "status": "string",
  "instruction": "string",
  "run_at": "string",
  "created_at": "string",
  "last_error": "string"
}

End users, spaces & sessions

Directory and governance. Conversation content is read here (for the operator), not streamed to integrations. Deleting a user is a crypto-shred cascade.

GET/manage/agent-stats

Per-agent usage: sessions, distinct people, last active.

Response · 200 · AgentStatsOut
rowsAgentStatRow[]requiredRows
Example response
{
  "rows": [
    {}
  ]
}
GET/manage/agents/{name}/sessions

A given agent's sessions across users/spaces.

Parameters
namepathstringrequired
limitqueryintegeroptional
cursorquerystring?optional
Response · 200 · AgentSessionPage
itemsAgentSessionOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
GET/manage/attachments/{aid}

Fetch one decrypted attachment file (ownership-checked).

Parameters
aidpathstringrequired

Response 200 · any

Example response
"…"
GET/manage/crawl

Current Crawl

Response 200 · CrawlOut?

Example response
{}
POST/manage/crawl/{job_id}/cancel

Cancel Crawl

Parameters
job_idpathstringrequired
Response · 200 · CrawlOut
idstringrequiredId
knowledge_basestringrequiredKnowledge Base
start_urlstringrequiredStart Url
statusstringrequiredStatus
error_codestring?requiredError Code
errorstring?requiredError
discoveredintegerrequiredDiscovered
fetchedintegerrequiredFetched
embeddedintegerrequiredEmbedded
skippedintegerrequiredSkipped
flaggedintegerrequiredFlagged
total_charsintegerrequiredTotal Chars
estimated_tokensintegerrequiredEstimated Tokens
tokens_usedintegerrequiredTokens Used
created_atstringrequiredCreated At
finished_atstring?requiredFinished At
Example response
{
  "id": "string",
  "knowledge_base": "string",
  "start_url": "string",
  "status": "string",
  "error_code": "string",
  "error": "string",
  "discovered": 0,
  "fetched": 0,
  "embedded": 0,
  "skipped": 0,
  "flagged": 0,
  "total_chars": 0,
  "estimated_tokens": 0,
  "tokens_used": 0,
  "created_at": "string",
  "finished_at": "string"
}
POST/manage/crawl/{job_id}/confirm

Confirm Crawl

Parameters
job_idpathstringrequired
Response · 200 · CrawlOut
idstringrequiredId
knowledge_basestringrequiredKnowledge Base
start_urlstringrequiredStart Url
statusstringrequiredStatus
error_codestring?requiredError Code
errorstring?requiredError
discoveredintegerrequiredDiscovered
fetchedintegerrequiredFetched
embeddedintegerrequiredEmbedded
skippedintegerrequiredSkipped
flaggedintegerrequiredFlagged
total_charsintegerrequiredTotal Chars
estimated_tokensintegerrequiredEstimated Tokens
tokens_usedintegerrequiredTokens Used
created_atstringrequiredCreated At
finished_atstring?requiredFinished At
Example response
{
  "id": "string",
  "knowledge_base": "string",
  "start_url": "string",
  "status": "string",
  "error_code": "string",
  "error": "string",
  "discovered": 0,
  "fetched": 0,
  "embedded": 0,
  "skipped": 0,
  "flagged": 0,
  "total_chars": 0,
  "estimated_tokens": 0,
  "tokens_used": 0,
  "created_at": "string",
  "finished_at": "string"
}
GET/manage/crawl/{job_id}/pages

Crawl Pages

Parameters
job_idpathstringrequired
Response · 200 · PageOut[]
urlstringrequiredUrl
statusstringrequiredStatus
titlestring?requiredTitle
charsintegerrequiredChars
reviewstringrequiredReview
review_notestring?requiredReview Note
similar_tostring?requiredSimilar To
errorstring?requiredError
Example response
[
  {
    "url": "string",
    "status": "string",
    "title": "string",
    "chars": 0,
    "review": "string",
    "review_note": "string",
    "similar_to": "string",
    "error": "string"
  }
]
DELETE/manage/documents/{doc_id}

Delete a user document.

Parameters
doc_idpathstringrequired

Response 204 — No Content (success, empty body).

POST/manage/end-user-token

Mint an end-user token for an integration's user (proxy-mode SSO handshake).

Request body · JSON
external_user_idstringrequiredExternal User Id
ttlinteger?optionalTtl
Example request
{
  "external_user_id": "string",
  "ttl": 0
}
Response · 200 · EndUserTokenOut
tokenstringrequiredToken
external_user_idstringrequiredExternal User Id
expires_inintegerrequiredExpires In
Example response
{
  "token": "string",
  "external_user_id": "string",
  "expires_in": 0
}
GET/manage/gaps

List Gaps

Parameters
unreadquerybooleanoptional
limitqueryintegeroptional
Response · 200 · GapOut[]
questionstringrequiredQuestion
timesintegerrequiredTimes
last_atstringrequiredLast At
agentsstring[]optionalAgents
readbooleanoptionalRead
Example response
[
  {
    "question": "string",
    "times": 0,
    "last_at": "string",
    "agents": [
      "string"
    ],
    "read": true
  }
]
GET/manage/gaps.csv

Export Gaps

Parameters
unreadquerybooleanoptional
limitqueryintegeroptional

Response 200 · any

Example response
"…"
POST/manage/gaps/read

Mark Gaps Read

Request body · JSON
questionsstring[]requiredQuestions
Example request
{
  "questions": [
    "string"
  ]
}

Response 200 · object — unstructured JSON (no fixed schema).

DELETE/manage/memories/{mid}

Delete one derived memory (governance).

Parameters
midpathstringrequired

Response 204 — No Content (success, empty body).

DELETE/manage/profiles/{pid}

Clear a profile (regenerates over the next conversations).

Parameters
pidpathstringrequired

Response 204 — No Content (success, empty body).

PUT/manage/profiles/{pid}

Edit a user profile (re-encrypted).

Parameters
pidpathstringrequired
Request body · JSON
contentstringrequiredContent
Example request
{
  "content": "string"
}
Response · 200 · ProfileOut
idstringrequiredId
agent_namestringrequiredAgent Name
contentstring?optionalContent
updated_atstringrequiredUpdated At
Example response
{
  "id": "string",
  "agent_name": "string",
  "content": "string",
  "updated_at": "string"
}
GET/manage/reviews

List Reviews

Parameters
statusquerystringoptional
limitqueryintegeroptional
Response · 200 · ReviewOut[]
idstringrequiredId
questionstringrequiredQuestion
answerstringrequiredAnswer
source_urlstring?requiredSource Url
source_titlestring?requiredSource Title
unsourcedstring[]optionalUnsourced
source_textstring?optionalSource Text
agent_namestring?requiredAgent Name
kb_namestring?requiredKb Name
statusstringrequiredStatus
created_atstringrequiredCreated At
Example response
[
  {
    "id": "string",
    "question": "string",
    "answer": "string",
    "source_url": "string",
    "source_title": "string",
    "unsourced": [
      "string"
    ],
    "source_text": "string",
    "agent_name": "string",
    "kb_name": "string",
    "status": "string",
    "created_at": "string"
  }
]
POST/manage/reviews/{rid}/approve

Approve Review

Parameters
ridpathstringrequired
Request body · JSON
kb_namestringrequiredKb Name
titlestring?optionalTitle
textstring?optionalText
Example request
{
  "kb_name": "string",
  "title": "string",
  "text": "string"
}
Response · 200 · ReviewOut
idstringrequiredId
questionstringrequiredQuestion
answerstringrequiredAnswer
source_urlstring?requiredSource Url
source_titlestring?requiredSource Title
unsourcedstring[]optionalUnsourced
source_textstring?optionalSource Text
agent_namestring?requiredAgent Name
kb_namestring?requiredKb Name
statusstringrequiredStatus
created_atstringrequiredCreated At
Example response
{
  "id": "string",
  "question": "string",
  "answer": "string",
  "source_url": "string",
  "source_title": "string",
  "unsourced": [
    "string"
  ],
  "source_text": "string",
  "agent_name": "string",
  "kb_name": "string",
  "status": "string",
  "created_at": "string"
}
POST/manage/reviews/{rid}/draft

Draft Review Entry

Parameters
ridpathstringrequired
langquerystring?optional
Response · 200 · DraftOut
textstring?requiredText
reasonstring?optionalReason
Example response
{
  "text": "string",
  "reason": "string"
}
POST/manage/reviews/{rid}/reject

Reject Review

Parameters
ridpathstringrequired
Response · 200 · ReviewOut
idstringrequiredId
questionstringrequiredQuestion
answerstringrequiredAnswer
source_urlstring?requiredSource Url
source_titlestring?requiredSource Title
unsourcedstring[]optionalUnsourced
source_textstring?optionalSource Text
agent_namestring?requiredAgent Name
kb_namestring?requiredKb Name
statusstringrequiredStatus
created_atstringrequiredCreated At
Example response
{
  "id": "string",
  "question": "string",
  "answer": "string",
  "source_url": "string",
  "source_title": "string",
  "unsourced": [
    "string"
  ],
  "source_text": "string",
  "agent_name": "string",
  "kb_name": "string",
  "status": "string",
  "created_at": "string"
}
GET/manage/sessions/{sid}/attachments

Attachments uploaded in a session (metadata).

Parameters
sidpathstringrequired
Response · 200 · AttachmentOut[]
idstringrequiredId
mimestringrequiredMime
namestringrequiredName
created_atstringrequiredCreated At
Example response
[
  {
    "id": "string",
    "mime": "string",
    "name": "string",
    "created_at": "string"
  }
]
GET/manage/sessions/{sid}/messages

A session's messages (paged; decrypted for the operator).

Parameters
sidpathstringrequired
limitqueryintegeroptional
cursorquerystring?optional
Response · 200 · MessagePage
itemsMessageOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
DELETE/manage/spaces/{sid}

Delete a space and its knowledge/sessions (default space cannot be deleted).

Parameters
sidpathstringrequired

Response 204 — No Content (success, empty body).

PATCH/manage/spaces/{sid}

Rename a space.

Parameters
sidpathstringrequired
Request body · JSON
namestringrequiredName
Example request
{
  "name": "string"
}
Response · 200 · SpaceOut
idstringrequiredId
namestringrequiredName
is_defaultbooleanrequiredIs Default
Example response
{
  "id": "string",
  "name": "string",
  "is_default": true
}
GET/manage/spaces/{sid}/agents

Agents added to a space.

Parameters
sidpathstringrequired

Response 200 · string[]

Example response
[
  "string"
]
POST/manage/spaces/{sid}/agents

Add an agent to a space.

Parameters
sidpathstringrequired
Request body · JSON
namestringrequiredName
Example request
{
  "name": "string"
}

Response 201 · string[]

Example response
[
  "string"
]
DELETE/manage/spaces/{sid}/agents/{name}

Remove an agent from a space.

Parameters
sidpathstringrequired
namepathstringrequired

Response 204 — No Content (success, empty body).

GET/manage/spaces/{sid}/documents

Documents in a space.

Parameters
sidpathstringrequired
limitqueryintegeroptional
cursorquerystring?optional
Response · 200 · DocumentPage
itemsDocumentOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
GET/manage/spaces/{sid}/memories

Long-term memories derived in a space (for governance).

Parameters
sidpathstringrequired
Response · 200 · MemoryOut[]
idstringrequiredId
kindstringrequiredKind
topicstring?optionalTopic
importanceintegerrequiredImportance
contentstring?optionalContent
session_idstring?optionalSession Id
created_atstringrequiredCreated At
updated_atstring?optionalUpdated At
Example response
[
  {
    "id": "string",
    "kind": "string",
    "topic": "string",
    "importance": 0,
    "content": "string",
    "session_id": "string",
    "created_at": "string",
    "updated_at": "string"
  }
]
GET/manage/spaces/{sid}/profiles

Per-agent user profiles in a space.

Parameters
sidpathstringrequired
Response · 200 · ProfileOut[]
idstringrequiredId
agent_namestringrequiredAgent Name
contentstring?optionalContent
updated_atstringrequiredUpdated At
Example response
[
  {
    "id": "string",
    "agent_name": "string",
    "content": "string",
    "updated_at": "string"
  }
]
GET/manage/spaces/{sid}/sessions

Sessions in a space.

Parameters
sidpathstringrequired
limitqueryintegeroptional
cursorquerystring?optional
Response · 200 · SessionPage
itemsSessionOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
GET/manage/users

List end users (?q=, ?sort=recent|tokens24h; keyset paging).

Parameters
limitqueryintegeroptional
cursorquerystring?optional
qquerystring?optional
sortquerystringoptional
Response · 200 · UserPage
itemsUserOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
curl "https://api.agent4.io/v1/manage/users?sort=tokens24h" -H "X-API-Key: $KEY"
DELETE/manage/users/{uid}

Delete a user and all their data (crypto-shred cascade).

Parameters
uidpathstringrequired

Response 204 — No Content (success, empty body).

GET/manage/users/{uid}

One user's detail (profile, contact, spaces).

Parameters
uidpathstringrequired
Response · 200 · UserDetailOut
idstringrequiredId
external_user_idstringrequiredExternal User Id
pref_namestring?optionalPref Name
created_atstringrequiredCreated At
space_countintegeroptionalSpace Count
session_countintegeroptionalSession Count
document_countintegeroptionalDocument Count
authstringoptionalAuth
emailstring?optionalEmail
email_verifiedboolean?optionalEmail Verified
tokens_24hintegeroptionalTokens 24H
spacesSpaceOut[]optionalSpaces
contact_emailstring?optionalContact Email
contact_phonestring?optionalContact Phone
pref_citystring?optionalPref City
pref_timezonestring?optionalPref Timezone
recent_refsobject[]optionalRecent Refs
Example response
{
  "id": "string",
  "external_user_id": "string",
  "pref_name": "string",
  "created_at": "string",
  "space_count": 0,
  "session_count": 0,
  "document_count": 0,
  "auth": "string",
  "email": "string",
  "email_verified": true,
  "tokens_24h": 0,
  "spaces": [
    {}
  ],
  "contact_email": "string",
  "contact_phone": "string",
  "pref_city": "string",
  "pref_timezone": "string",
  "recent_refs": [
    {}
  ]
}
GET/manage/users/{uid}/documents

A user's uploaded documents.

Parameters
uidpathstringrequired
limitqueryintegeroptional
cursorquerystring?optional
Response · 200 · DocumentPage
itemsDocumentOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
GET/manage/users/{uid}/knowledge-graph

3D projection of a user's memories / KB chunks.

Parameters
uidpathstringrequired
sourcequerystringoptional
space_idquerystring?optional
limitqueryinteger?optional
refreshquerybooleanoptional
qquerystringoptional
streamquerybooleanoptional

Response 200 · object — unstructured JSON (no fixed schema).

GET/manage/users/{uid}/knowledge-graph/items/{item_id}

User Graph Item

Parameters
uidpathstringrequired
item_idpathstringrequired
sourcequerystringoptional

Response 200 · object — unstructured JSON (no fixed schema).

POST/manage/users/{uid}/password

Admin-reset an email user's password (404 for non-email accounts).

Parameters
uidpathstringrequired
Request body · JSON
new_passwordstringrequiredNew Password
Example request
{
  "new_password": "string"
}

Response 204 — No Content (success, empty body).

GET/manage/users/{uid}/sessions

A user's chat sessions (metadata; no message content).

Parameters
uidpathstringrequired
limitqueryintegeroptional
cursorquerystring?optional
Response · 200 · SessionPage
itemsSessionOut[]requiredItems
next_cursorstring?optionalNext Cursor
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string"
}
POST/manage/users/{uid}/spaces

Create a space for a user.

Parameters
uidpathstringrequired
Request body · JSON
namestringrequiredName
Example request
{
  "name": "string"
}
Response · 201 · SpaceOut
idstringrequiredId
namestringrequiredName
is_defaultbooleanrequiredIs Default
Example response
{
  "id": "string",
  "name": "string",
  "is_default": true
}
GET/manage/users/{uid}/usage

Per-user token usage time series.

Parameters
uidpathstringrequired
hoursqueryintegeroptional
daysqueryintegeroptional
Response · 200 · UserUsageOut
pointsobject[]requiredPoints
total_tokensintegerrequiredTotal Tokens
Example response
{
  "points": [
    {}
  ],
  "total_tokens": 0
}

Usage & quota

Metadata only — token counts and event counts, never conversation content.

GET/manage/usage

Token usage; ?group=total|agent|user|space|hour|day|week|model|kind.

Parameters
groupquerystringoptional
sincequerystring?optional
Response · 200 · UsageOut
groupstringrequiredGroup
totalUsageRowrequired
rowsUsageRow[]requiredRows
Example response
{
  "group": "string",
  "total": {},
  "rows": [
    {}
  ]
}
curl "https://api.agent4.io/v1/manage/usage?group=agent" -H "X-API-Key: $KEY"
GET/tenant/quota

Quota snapshot (used vs monthly ceiling) for banners/progress bars.

Response 200 · object — unstructured JSON (no fixed schema).

Tenant settings & security

GET/tenant/audit

Audit trail: every configuration change with who, when and before/after. Covers the console, this API and MCP alike. Filter with ?entity=agent|skill|knowledge_base|… , ?action= , ?q= (object name). Cursor-paged, newest first. There is no delete endpoint — entries are immutable by design.

Parameters
actionquerystring?optional
entityquerystring?optional
qquerystring?optional
changes_onlyquerybooleanoptional
date_fromquerystring?optional
date_toquerystring?optional
limitqueryintegeroptional
offsetqueryintegeroptional
cursorquerystring?optional
Response · 200 · TenantAuditPage
itemsTenantAuditOut[]requiredItems
next_cursorstring?optionalNext Cursor
totalinteger?optionalTotal
Example response
{
  "items": [
    {}
  ],
  "next_cursor": "string",
  "total": 0
}
curl "https://api.agent4.io/v1/tenant/audit?entity=agent&limit=50" -H "X-API-Key: $KEY"
GET/tenant/audit.csv

The same trail as a CSV download, taking the same filters. before/after are JSON so the file stays machine-readable. Use this to archive beyond the two-year retention.

Parameters
actionquerystring?optional
entityquerystring?optional
qquerystring?optional
changes_onlyquerybooleanoptional
date_fromquerystring?optional
date_toquerystring?optional
limitqueryintegeroptional

Response 200 · any

Example response
"…"
curl "https://api.agent4.io/v1/tenant/audit.csv?entity=agent" -H "X-API-Key: $KEY" -o audit.csv
DELETE/tenant/custom-domain

Delete Custom Domain

Response 204 — No Content (success, empty body).

GET/tenant/custom-domain

Get Custom Domain

Response 200 · CustomDomainOut?

Example response
{}
PUT/tenant/custom-domain

Set Custom Domain

Request body · JSON
domainstringrequiredDomain
agent_aliasstring?optionalAgent Alias
Example request
{
  "domain": "string",
  "agent_alias": "string"
}
Response · 200 · CustomDomainOut
domainstringrequiredDomain
agent_aliasstring?optionalAgent Alias
statusstringrequiredStatus
cname_targetstringrequiredCname Target
last_checked_atstring?optionalLast Checked At
last_errorstring?optionalLast Error
Example response
{
  "domain": "string",
  "agent_alias": "string",
  "status": "string",
  "cname_target": "string",
  "last_checked_at": "string",
  "last_error": "string"
}
POST/tenant/custom-domain/check

Check Custom Domain

Response · 200 · CustomDomainOut
domainstringrequiredDomain
agent_aliasstring?optionalAgent Alias
statusstringrequiredStatus
cname_targetstringrequiredCname Target
last_checked_atstring?optionalLast Checked At
last_errorstring?optionalLast Error
Example response
{
  "domain": "string",
  "agent_alias": "string",
  "status": "string",
  "cname_target": "string",
  "last_checked_at": "string",
  "last_error": "string"
}
GET/tenant/custom-domain/feature

Custom Domain Feature

Response 200 · object — unstructured JSON (no fixed schema).

GET/tenant/keys

List your API keys (metadata; never plaintext).

Response · 200 · ApiKeyOut[]
idstringrequiredId
namestringoptionalName
revokedbooleanrequiredRevoked
created_atstringrequiredCreated At
Example response
[
  {
    "id": "string",
    "name": "string",
    "revoked": true,
    "created_at": "string"
  }
]
POST/tenant/keys

Mint a new API key (plaintext returned once).

Response · 201 · IssuedKeyOut
idstringrequiredId
api_keystringrequiredApi Key
Example response
{
  "id": "string",
  "api_key": "string"
}
curl -X POST https://api.agent4.io/v1/tenant/keys -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"name":"backend"}'
DELETE/tenant/keys/{kid}

Delete My Key

Parameters
kidpathstringrequired

Response 204 — No Content (success, empty body).

POST/tenant/keys/{kid}/revoke

Revoke a key (cannot revoke the last active one).

Parameters
kidpathstringrequired

Response 204 — No Content (success, empty body).

GET/tenant/me

Your tenant identity (id, name).

Response · 200 · TenantMeOut
tenant_idstringrequiredTenant Id
namestringrequiredName
auth_modestringrequiredAuth Mode
aliasstring?optionalAlias
public_basestring?optionalPublic Base
Example response
{
  "tenant_id": "string",
  "name": "string",
  "auth_mode": "string",
  "alias": "string",
  "public_base": "string"
}
DELETE/tenant/oauth/{provider}

Clear a provider's credentials.

Parameters
providerpathstringrequired

Response 204 — No Content (success, empty body).

PUT/tenant/oauth/{provider}

Set social-login credentials for a provider (google | twitter).

Parameters
providerpathstringrequired
Request body · JSON
client_idstringrequiredClient Id
client_secretstringrequiredClient Secret
Example request
{
  "client_id": "string",
  "client_secret": "string"
}

Response 204 — No Content (success, empty body).

PUT/tenant/oauth/{provider}/enabled

Enable / disable a provider (decoupled from whether creds are set).

Parameters
providerpathstringrequired
Request body · JSON
enabledbooleanrequiredEnabled
Example request
{
  "enabled": true
}

Response 204 — No Content (success, empty body).

GET/tenant/privacy

Get privacy / BYOK settings.

Response · 200 · ByokOut
tenant_idstringrequiredTenant Id
privacy_modebooleanrequiredPrivacy Mode
byok_providerstring?optionalByok Provider
Example response
{
  "tenant_id": "string",
  "privacy_mode": true,
  "byok_provider": "string"
}
PUT/tenant/privacy

Update privacy / BYOK settings.

Request body · JSON
privacy_modebooleanrequiredPrivacy Mode
byok_configobject?optionalByok Config
Example request
{
  "privacy_mode": true,
  "byok_config": {}
}
Response · 200 · ByokOut
tenant_idstringrequiredTenant Id
privacy_modebooleanrequiredPrivacy Mode
byok_providerstring?optionalByok Provider
Example response
{
  "tenant_id": "string",
  "privacy_mode": true,
  "byok_provider": "string"
}
GET/tenant/settings

Get tenant settings (name, alias, auth mode, profile, onboarding).

Response · 200 · TenantSettingsOut
tenant_idstringrequiredTenant Id
namestringrequiredName
aliasstring?optionalAlias
alias_prefixstringoptionalAlias Prefix
auth_modestringrequiredAuth Mode
privacy_modebooleanrequiredPrivacy Mode
statusstringrequiredStatus
profileobject?optionalProfile
onboarding_configobject?optionalOnboarding Config
oauthobject[]optionalOauth
smtpobject?optionalSmtp
Example response
{
  "tenant_id": "string",
  "name": "string",
  "alias": "string",
  "alias_prefix": "string",
  "auth_mode": "string",
  "privacy_mode": true,
  "status": "string",
  "profile": {},
  "onboarding_config": {},
  "oauth": [
    {}
  ],
  "smtp": {}
}
PATCH/tenant/settings

Update tenant settings.

Request body · JSON
namestring?optionalName
aliasstring?optionalAlias
auth_modestring?optionalAuth Mode
profileobject?optionalProfile
onboarding_configobject?optionalOnboarding Config
Example request
{
  "name": "string",
  "alias": "string",
  "auth_mode": "string",
  "profile": {},
  "onboarding_config": {}
}
Response · 200 · TenantSettingsOut
tenant_idstringrequiredTenant Id
namestringrequiredName
aliasstring?optionalAlias
alias_prefixstringoptionalAlias Prefix
auth_modestringrequiredAuth Mode
privacy_modebooleanrequiredPrivacy Mode
statusstringrequiredStatus
profileobject?optionalProfile
onboarding_configobject?optionalOnboarding Config
oauthobject[]optionalOauth
smtpobject?optionalSmtp
Example response
{
  "tenant_id": "string",
  "name": "string",
  "alias": "string",
  "alias_prefix": "string",
  "auth_mode": "string",
  "privacy_mode": true,
  "status": "string",
  "profile": {},
  "onboarding_config": {},
  "oauth": [
    {}
  ],
  "smtp": {}
}
POST/tenant/settings/logo

Upload the login-page logo.

Request body · multipart/form-data
filestringrequiredFile
Example request
{
  "file": "string"
}

Response 200 · object — unstructured JSON (no fixed schema).

PUT/tenant/settings/smtp

Set tenant SMTP (password sealed with the platform KEK; empty host clears).

Request body · JSON
hoststringoptionalHost
portintegeroptionalPort
userstringoptionalUser
passwordstring?optionalPassword
from_addrstringoptionalFrom Addr
starttlsbooleanoptionalStarttls
Example request
{
  "host": "string",
  "port": 0,
  "user": "string",
  "password": "string",
  "from_addr": "string",
  "starttls": true
}
Response · 200 · TenantSettingsOut
tenant_idstringrequiredTenant Id
namestringrequiredName
aliasstring?optionalAlias
alias_prefixstringoptionalAlias Prefix
auth_modestringrequiredAuth Mode
privacy_modebooleanrequiredPrivacy Mode
statusstringrequiredStatus
profileobject?optionalProfile
onboarding_configobject?optionalOnboarding Config
oauthobject[]optionalOauth
smtpobject?optionalSmtp
Example response
{
  "tenant_id": "string",
  "name": "string",
  "alias": "string",
  "alias_prefix": "string",
  "auth_mode": "string",
  "privacy_mode": true,
  "status": "string",
  "profile": {},
  "onboarding_config": {},
  "oauth": [
    {}
  ],
  "smtp": {}
}
POST/tenant/settings/smtp/test

Send a test email with the current SMTP config.

Parameters
toquerystringrequired

Response 204 — No Content (success, empty body).

Building with a coding agent instead? The Cookbook has the same operations as ready-to-run recipes over MCP — no manual HTTP.