Skip to content

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.

OperationEndpointScope
Create an agent (create_agent)POST /api/v1/agentsworkflows:write
List agents (list_agents)GET /api/v1/agentsworkflows: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}/publishworkflows:publish
Build from a compact spec (create_agent_from_spec)POST /api/v1/agents/from-specworkflows:write
Generate from a description (generate_agent)POST /api/v1/agents/generateworkflows: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"] }'
FieldValues
name1–200 characters
descriptionOptional, defaults to empty
channelsAt least one, e.g. ["web"]
nodes / edgesOptional — 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:

FieldMeaning
id, name, descriptionAs set
statusdraft, testing, published, archived or paused
channelsOne per Trigger on the canvas, e.g. ["web", "whatsapp", "phone"]; empty for an agent started only by a webhook or a schedule
active_versionThe published version number
node_countHow many nodes its graph has
created_at / updated_atTimestamps

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. nodes and edges stay exactly what customers get; GET shows has_unpublished_changes: true and the draft. 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, description and channels apply straight away; they are not part of the draft.
  • Setting a published agent's status to draft, testing, archived or paused takes 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
  }'
FieldValues
name, persona_name, role, system_promptRequired
toneOptional: professional, friendly, empathetic, casual or authoritative
greetingOptional
channelOptional, defaults to web
publishOptional — 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 ​

HTTPCodeMeaning
400invalid_requestA field is missing or malformed, or an empty update
403insufficient_scopeThe key lacks the operation's scope — or publish: true without workflows:publish
404not_foundNo agent with that id
409agent_changedThe agent changed while your update was saving — send it again
422not_publishableThe agent failed validation; validation_errors names the nodes
502generation_failedGenerate only: the model failed or returned an unusable spec
503missing_system_llmGenerate 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