Agents APICopy Anchor Link

The Action Agents API provides discovery and chat for agents configured in Action Agent Studio. It does not configure agents.

curl -X GET 'https://api.actionflows.ai/api/action-agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json'

Send a request to see the response.

Authentication and organization scopeCopy Anchor Link

Send the API key as a bearer token:

Authorization: Bearer YOUR_API_KEY

Every operation is organization-scoped. The resolver uses the authenticated context's organization; an organization-scoped API key supplies its key organization.

• An organization-scoped API key supplies its key organization, so organizationId may be omitted on discovery routes; if supplied, it must match.
• A user-scoped API key has no active organization in this context, so GET /api/action-agents must include an authorized organizationId.
• An authenticated application session may omit organizationId when activeOrganizationId is present, or provide another authorized organization. If neither source supplies one, the request is forbidden.

GET /api/action-agents/{actionAgentId} may omit organizationId because the gateway loads the agent and authorizes its owning organization. If supplied, the value must match that organization.

List and get agentsCopy Anchor Link

GET /api/action-agents?organizationId={organizationId}
GET /api/action-agents/{actionAgentId}?organizationId={organizationId}

The response contains discovery metadata only: id, name, description, slug, active, organizationId, selected service and model names, tags, and timestamps. It does not contain the system prompt, Action Agent Studio layout, tool configuration, MCP configuration, provider credential mode, or configVersion.

Chat completions (OpenAI-compatible)Copy Anchor Link

Chat runs on the OpenAI-compatible endpoint. Pass the Action Agent id as model:

POST /v1/chat/completions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "model": "{actionAgentId}",
  "messages": [
    { "role": "user", "content": "Where is my invoice?" }
  ]
}

Request fields the endpoint reads:

Other OpenAI fields (temperature, max_tokens, tools, n, ...) are ignored: the agent configuration owns sampling and tools. The last user message is trimmed, empty text is rejected, and the maximum length is 100,000 characters.

Sessions and the response headerCopy Anchor Link

The OpenAI protocol has no session concept. Every request without X-ActionFlows-Session-Id starts a new durable session; the response always carries the id:

X-ActionFlows-Session-Id: {sessionId}

Send that header back to continue the same conversation, memory, and transcript. A wrong, closed, deleted, or foreign session id returns 404 with code session_not_found; it never creates a replacement session.

Non-streaming responseCopy Anchor Link

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "agent_123",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Your latest invoice is paid." },
      "finish_reason": "stop",
      "logprobs": null
    }
  ]
}

StreamingCopy Anchor Link

With "stream": true the endpoint returns OpenAI SSE chunks and terminates with data: [DONE]:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1730000000,"model":"agent_123","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1730000000,"model":"agent_123","choices":[{"index":0,"delta":{"content":"Your latest invoice"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1730000000,"model":"agent_123","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

A runtime failure mid-stream emits one data: {"error": {...}} frame instead of [DONE]. When a Lead Agent gates the turn, the stream ends with finish_reason: "stop" and no further content; the approved submission is delivered later and recorded on the Lead Review work item.

OpenAI-compatible errorsCopy Anchor Link

Errors use the OpenAI envelope:

{ "error": { "message": "...", "type": "invalid_request_error", "code": "model_not_found", "param": "model" } }

cURL examplesCopy Anchor Link

List agentsCopy Anchor Link

curl -X GET "https://api.actionflows.ai/api/action-agents?organizationId=org_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Chat (non-streaming)Copy Anchor Link

curl -X POST "https://api.actionflows.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_123","messages":[{"role":"user","content":"Where is my invoice?"}]}'

Chat (streaming)Copy Anchor Link

curl -N -X POST "https://api.actionflows.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent_123","messages":[{"role":"user","content":"Explain the refund policy briefly."}],"stream":true}'

Continue a sessionCopy Anchor Link

Send the X-ActionFlows-Session-Id value from the previous response:

curl -X POST "https://api.actionflows.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-ActionFlows-Session-Id: sess_123" \
  -d '{"model":"agent_123","messages":[{"role":"user","content":"And the second one?"}]}'

OpenAI SDK exampleCopy Anchor Link

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ACTIONFLOWS_API_KEY,
  baseURL: "https://api.actionflows.ai/v1",
});

const completion = await client.chat.completions.create({
  model: "agent_123",
  messages: [{ role: "user", content: "Where is my invoice?" }],
});

console.log(completion.choices[0]?.message.content);

The Agent API has no endpoint to close, delete, list, or fetch the full transcript of a session. The separate public Explore visitor endpoint can return a bounded recent transcript; see Sessions & chat.

See alsoCopy Anchor Link

• Action Agent lifecycle
• Sessions & chat
• TypeScript SDK
• Hosted MCP
• Limits
• Troubleshooting