Agents API
REST API for ActionFlows Agents: list and get discovery metadata, start sessions, send messages, and stream SSE. Author agents in Studio; Trigger credentials stay server-side.
Agents API
REST endpoints for org agents and sessions. For product concepts (Studio, skills, MCP, when to use an agent vs a flow), read Agents first.
ActionFlows proxies chat on the server. Never expose Trigger PATs to browsers or end users. Call this API from your backend with an organization API key.
Design agents in Action Agent Studio. The public API does not create, update, or delete agents, and does not return Studio fields such as system prompt, layout, tools, or MCP connection details.
Try it
Live requests run from your browser. Open the API Explorer to try every operation from one screen.
/api/action-agentsList agents
Requests go to the live API from your browser. The docs server never sees this key.
curl -X GET 'https://api.actionflows.ai/api/action-agents' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Accept: application/json'
Response
Send a request to see the response.
REST API
List / get agents
GET /api/action-agents?organizationId=...
GET /api/action-agents/{actionAgentId}Responses are discovery metadata only (for example id, name, slug, active, organizationId, model ids, timestamps). Use them to pick an agent id for chat. Do not use them to sync Studio configuration.
Start a session
POST /api/action-agents/{actionAgentId}/sessions{
"organizationId": "org_123",
"endUserId": "user_abc"
}Response:
{
"success": true,
"data": {
"sessionId": "sess_...",
"externalId": "..."
}
}Use sessionId in subsequent calls. Trigger credentials are never returned.
Send a message (wait for reply)
POST /api/action-agents/{actionAgentId}/sessions/{sessionId}/messages{
"organizationId": "org_123",
"message": "What is my invoice status?"
}Response:
{
"success": true,
"data": {
"text": "Your latest invoice is paid."
}
}Stream a message (SSE)
Same path with Accept: text/event-stream. Events:
data: {"type":"text-delta","delta":"Hello"}
data: {"type":"done","text":"Hello"}Resume a stream
GET /api/action-agents/{actionAgentId}/sessions/{sessionId}/stream?organizationId=...Optional Last-Event-ID / lastEventId resumes from the persisted cursor.
Example requests
List agents (cURL)
curl -X GET "https://api.actionflows.ai/api/action-agents?organizationId=org_123" \
-H "Authorization: Bearer YOUR_API_KEY"Start a session (cURL)
curl -X POST https://api.actionflows.ai/api/action-agents/agent_123/sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"organizationId":"org_123","endUserId":"user_abc"}'Send a message (cURL)
curl -X POST https://api.actionflows.ai/api/action-agents/agent_123/sessions/sess_123/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"organizationId":"org_123","message":"Hello!"}'Stream a message (cURL)
curl -N -X POST https://api.actionflows.ai/api/action-agents/agent_123/sessions/sess_123/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: text/event-stream" \
-H "Content-Type: application/json" \
-d '{"organizationId":"org_123","message":"Explain refunds briefly."}'JavaScript (Fetch)
const headers = {
Authorization: "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
};
const agentsResponse = await fetch(
"https://api.actionflows.ai/api/action-agents?organizationId=org_123",
{ headers },
);
const agents = await agentsResponse.json();
const sessionResponse = await fetch(
"https://api.actionflows.ai/api/action-agents/agent_123/sessions",
{
method: "POST",
headers,
body: JSON.stringify({ organizationId: "org_123", endUserId: "user_abc" }),
},
);
const session = await sessionResponse.json();
const sessionId = session.data.sessionId;
const messageResponse = await fetch(
`https://api.actionflows.ai/api/action-agents/agent_123/sessions/${sessionId}/messages`,
{
method: "POST",
headers,
body: JSON.stringify({ organizationId: "org_123", message: "Hello!" }),
},
);
const message = await messageResponse.json();
console.log(message.data.text);Python (requests)
import requests
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
}
base = "https://api.actionflows.ai/api/action-agents/agent_123"
session = requests.post(
f"{base}/sessions",
headers=headers,
json={"organizationId": "org_123", "endUserId": "user_abc"},
).json()
session_id = session["data"]["sessionId"]
reply = requests.post(
f"{base}/sessions/{session_id}/messages",
headers=headers,
json={"organizationId": "org_123", "message": "Hello!"},
).json()
print(reply["data"]["text"])Keep the API key on the server. Do not embed it in client-side apps.