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.

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. Machine-readable spec: openapi.json.

Agents

POST/agents/{name}

Create or replace an agent (full PUT semantics — send every field you want to keep).

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","tools":["web_search"],"published":true}'
GET/agents

List your agents.

GET/agents/{name}

Get one agent's full configuration.

Knowledge bases

POST/knowledge-bases

Create a knowledge base.

curl -X POST https://api.agent4.io/v1/knowledge-bases -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"Company policy","instructions":"Authoritative current policy."}'
POST/knowledge-bases/{name}/documents/upload

Upload a file (pdf/docx/…) or a zip of a folder — subfolders are walked and imported.

curl -X POST "https://api.agent4.io/v1/knowledge-bases/Company%20policy/documents/upload" \
  -H "X-API-Key: $KEY" -F "file=@/path/to/policy.pdf"
POST/knowledge-bases/{name}/search

Search the base — verify a real question retrieves before you rely on it.

curl -X POST "https://api.agent4.io/v1/knowledge-bases/Company%20policy/search" -H "X-API-Key: $KEY" \
  -H 'Content-Type: application/json' -d '{"query":"late fee"}'

Your MCP servers & tools

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

POST/mcp-servers

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

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"}}'
GET/mcp-servers

List the MCP servers registered on your tenant.

Storylines

Multi-step, stateful flows. See the cookbook recipe for the graph shape.

POST/storylines

Create a Storyline draft (a graph of nodes with conditional exits).

POST/storylines/{id}/validate

Validate the graph — required before publishing.

POST/storylines/{id}/publish

Freeze an immutable version and go live.

Usage & end users

GET/manage/usage?group=agent

Usage metadata (token counts, event counts) — never conversation content.

curl "https://api.agent4.io/v1/manage/usage?group=agent" -H "X-API-Key: $KEY"
GET/manage/users

List your end users (email / login method).

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