Agents
Create, edit and publish agents from your own systems — the same agents you build on the Studio canvas. Each operation is also available to MCP-capable agents as the tool named in brackets.
| Operation | Endpoint | Scope |
|---|---|---|
Create an agent (create_agent) | POST /api/v1/agents | workflows:write |
List agents (list_agents) | GET /api/v1/agents | workflows:read |
Get an agent with its graph (get_agent) | GET /api/v1/agents/{id} | workflows:read |
Update an agent (update_agent) | PATCH /api/v1/agents/{id} | workflows:write |
Publish an agent (publish_agent) | POST /api/v1/agents/{id}/publish | workflows:publish |
Build from a compact spec (create_agent_from_spec) | POST /api/v1/agents/from-spec | workflows:write |
Generate from a description (generate_agent) | POST /api/v1/agents/generate | workflows:write |
Creating an agent
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/agents" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{ "name": "Support Assistant", "channels": ["web"] }'| Field | Values |
|---|---|
name | 1–200 characters |
description | Optional, defaults to empty |
channels | At least one, e.g. ["web"] |
nodes / edges | Optional — the full graph: a Trigger, an AI Agent and its Persona and Chat Model sub-nodes, linked by typed edges such as ai_persona and ai_chat_model. Leave them out and fill the graph in later with PATCH |
The response is 201 with the agent. A new agent is always a draft; publishing is a separate call.
Don't want to write a graph? Use from spec or generate.
Listing and reading agents
GET /api/v1/agents returns { "data": [...] } — at most 200 agents, most recently updated first. Each row is a summary:
| Field | Meaning |
|---|---|
id, name, description | As set |
status | draft, testing, published, archived or paused |
channels | One per Trigger on the canvas, e.g. ["web", "whatsapp", "phone"]; empty for an agent started only by a webhook or a schedule |
active_version | The published version number |
node_count | How many nodes its graph has |
created_at / updated_at | Timestamps |
The test copies the Studio makes when you try out a draft are never listed.
GET /api/v1/agents/{id} adds the graph — nodes and edges — plus has_unpublished_changes and, when there is one, the draft (nodes, edges, updated_at, base_version). An unknown id is 404 not_found.
Secrets stay hidden
A secret stored on a node (an HTTP header value, a webhook secret) is never returned. Reads show the placeholder __perfox_stored_secret__ in its place. Send that placeholder back unchanged in a PATCH and the stored secret is kept, so you can read an agent, edit it and write it back without re-entering secrets.
Updating an agent
PATCH /api/v1/agents/{id} takes any of name, description, channels, a replacement graph (nodes and/or edges, replaced wholesale — attach tools, MCP servers or Knowledge Base by including their sub-nodes and edges), or a status of draft, testing, archived or paused. Publishing is its own operation. Send at least one field, or the request is refused with 400 invalid_request.
Edits to a live agent are a draft until you publish
Your customers keep talking to the version you published while you work on the next one.
- On a published agent — or a sub-flow that a published agent runs — a graph change is saved as the agent's draft.
nodesandedgesstay exactly what customers get;GETshowshas_unpublished_changes: trueand thedraft. This is the same rule as saving on the Studio canvas. - A draft that ends up identical to the live graph is dropped — there is nothing to publish.
name,descriptionandchannelsapply straight away; they are not part of the draft.- Setting a published agent's
statustodraft,testing,archivedorpausedtakes it off live: its draft (with this request's graph on top) becomes the stored graph. - An agent that isn't published is edited in place.
- If the agent changed while your update was saving, the call answers
409 agent_changed— send it again.
Publishing
POST /api/v1/agents/{id}/publish validates the agent — its draft, when it has unpublished changes — saves a new version and takes it live:
json
{ "id": "01a0…", "status": "published", "version": 4 }Any drafts in the sub-flows it runs go live with it. If the agent can't be published, the call answers 422 not_publishable with validation_errors naming the nodes to fix, and the live version stays as it was. An unknown id is 404 not_found.
Building from a spec or a description
From a spec — POST /api/v1/agents/from-spec builds the standard agent (a Trigger, an AI Agent, a Persona and a Chat Model) from a few fields:
bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/agents/from-spec" \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Assistant",
"persona_name": "Maya",
"role": "Support Agent",
"tone": "friendly",
"system_prompt": "You help Acme customers track orders and returns.",
"greeting": "Hi, I am Maya. How can I help?",
"channel": "web",
"publish": true
}'| Field | Values |
|---|---|
name, persona_name, role, system_prompt | Required |
tone | Optional: professional, friendly, empathetic, casual or authoritative |
greeting | Optional |
channel | Optional, defaults to web |
publish | Optional — publish straight away |
From a description — POST /api/v1/agents/generate takes a plain-language prompt (plus optional channel and publish). A model drafts the persona and system prompt, then the same standard graph is built.
Both answer 201:
json
{ "id": "01a0…", "name": "Support Assistant", "status": "published", "channels": ["web"], "node_count": 4, "published": true, "version": 1 }publish: true needs the workflows:publish scope. Without it, the agent is still created as a draft and the call answers 403 insufficient_scope.
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed, or an empty update |
| 403 | insufficient_scope | The key lacks the operation's scope — or publish: true without workflows:publish |
| 404 | not_found | No agent with that id |
| 409 | agent_changed | The agent changed while your update was saving — send it again |
| 422 | not_publishable | The agent failed validation; validation_errors names the nodes |
| 502 | generation_failed | Generate only: the model failed or returned an unusable spec |
| 503 | missing_system_llm | Generate only: agent generation is unavailable right now |
You can now …
- Create agents from a graph, a compact spec or a plain-language description
- Read an agent's live graph and its unpublished draft side by side
- Edit a live agent safely — customers keep the published version until you publish
- Publish with validation, and see exactly which nodes block it