Agents API

Overview

The Agents API is the core of Arcanflows. It lets you create AI agents backed by any supported LLM, attach tools and knowledge bases, configure sub-agent delegation, and interact via synchronous chat, SSE streaming, or async jobs.

---

Endpoint Summary

Core CRUD

Chat & Runtime

Sub-Agents

Training & Knowledge

Stats & Logs

SerpAPI (Web Search)

Public / Embed

---

List Agents

GET /api/v1/agents

Query Parameters

Example

bashCopy
curl "https://your-instance.arcanflows.com/api/v1/agents?status=published&per_page=10" \
  -H "Authorization: Bearer <your_login_jwt>"

Response

jsonCopy
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Support Bot",
      "description": "Handles customer inquiries",
      "primary_model": "gpt-4o",
      "status": "published",
      "temperature": 0.7,
      "created_at": "2026-03-10T08:00:00Z",
      "updated_at": "2026-04-01T12:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 3,
    "total_pages": 1
  }
}

---

Create Agent

POST /api/v1/agents

Request Body

Available Models

Models depend on what backends and Ollama models are configured on your instance. Common options:

Example

bashCopy
curl -X POST "https://your-instance.arcanflows.com/api/v1/agents" \
  -H "Authorization: Bearer <your_login_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "primary_model": "gpt-4o",
    "system_prompt": "You are a helpful customer support assistant for Acme Inc. Answer questions accurately and politely.",
    "temperature": 0.7,
    "max_tokens": 2048
  }'

Response (201 Created)

jsonCopy
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Support Bot",
  "description": "",
  "primary_model": "gpt-4o",
  "system_prompt": "You are a helpful customer support assistant for Acme Inc. Answer questions accurately and politely.",
  "temperature": 0.7,
  "max_tokens": 2048,
  "status": "draft",
  "created_at": "2026-04-12T09:00:00Z",
  "updated_at": "2026-04-12T09:00:00Z"
}

---

Get Agent

GET /api/v1/agents/:id

Returns the full agent object including tools, knowledge base status, and sub-agent configuration.

Example

bashCopy
curl "https://your-instance.arcanflows.com/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <your_login_jwt>"

Response

jsonCopy
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Support Bot",
  "description": "Handles customer inquiries",
  "primary_model": "gpt-4o",
  "system_prompt": "You are a helpful customer support assistant...",
  "temperature": 0.7,
  "max_tokens": 2048,
  "status": "published",
  "tools": [
    {
      "id": "tool-uuid-here",
      "name": "Get Order Status",
      "tool_type": "rest_api",
      "is_enabled": true
    }
  ],
  "knowledge_base": {
    "enabled": true,
    "document_count": 15,
    "chunk_count": 342
  },
  "sub_agents": [
    {
      "id": "sub-agent-uuid",
      "name": "Billing Assistant",
      "relationship_type": "template"
    }
  ],
  "created_at": "2026-03-10T08:00:00Z",
  "updated_at": "2026-04-01T12:30:00Z"
}

---

Update Agent

PUT /api/v1/agents/:id

Send only the fields you want to update.

Example

bashCopy
curl -X PUT "https://your-instance.arcanflows.com/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <your_login_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot v2",
    "temperature": 0.5,
    "status": "published"
  }'

Returns the updated agent object.

---

Delete Agent

DELETE /api/v1/agents/:id

bashCopy
curl -X DELETE "https://your-instance.arcanflows.com/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <your_login_jwt>"

Returns 204 No Content on success.

---

Chat with Agent (Synchronous)

POST /api/v1/agents/:id/chat

Sends a message and waits for the full response. This endpoint requires a console JWT (it is what the web app uses).

Calling an agent from your own code? Use the public endpoint instead — POST /api/v1/public/agents/:id/chat — authenticated with an Embed API Key (emb_). Its body is { "session_id", "message" } and the reply is in assistant_reply.content. Full details on the API overview and Authentication pages. The examples below use the console-JWT endpoint.

Request Body

Example

bashCopy
curl -X POST "https://your-instance.arcanflows.com/api/v1/agents/AGENT_ID/chat" \
  -H "Authorization: Bearer <your_login_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How do I reset my password?",
    "conversation_id": "conv-uuid-here"
  }'

Response

jsonCopy
{
  "conversation_id": "conv-uuid-here",
  "message": {
    "id": "msg-uuid-here",
    "role": "assistant",
    "content": "To reset your password:\n\n1. Go to Settings > Security\n2. Click Reset Password\n3. Check your email for the reset link\n\nLet me know if you need anything else!",
    "created_at": "2026-04-12T09:15:00Z"
  },
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 85,
    "total_tokens": 235
  },
  "sources": [
    {
      "document_name": "Password Reset Guide.pdf",
      "chunk_preview": "To reset your password, navigate to...",
      "relevance_score": 0.92
    }
  ],
  "tool_calls": []
}

---

Chat with Agent (SSE Streaming)

POST /api/v1/agents/:id/chat/stream

Returns a Server-Sent Events stream. The request body is identical to the synchronous chat endpoint.

SSE Event Format

event: message_start
data: {"conversation_id": "conv-uuid", "message_id": "msg-uuid"}

event: content_delta
data: {"delta": "To reset"}

event: content_delta
data: {"delta": " your password"}

event: tool_use
data: {"tool": "get_user_info", "input": {"user_id": "123"}}

event: tool_result
data: {"tool": "get_user_info", "output": {"email": "[email protected]"}}

event: message_stop
data: {"usage": {"prompt_tokens": 150, "completion_tokens": 85}}

JavaScript Streaming Example

javascriptCopy
const response = await fetch(
  "https://your-instance.arcanflows.com/api/v1/agents/AGENT_ID/chat/stream",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <your_login_jwt>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "Tell me about your services" }),
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split("\n");

  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      if (data.delta) {
        process.stdout.write(data.delta);
      }
    }
  }
}

---

Async Chat

POST /api/v1/agents/:id/chat/async

Starts a chat job and immediately returns a job ID. Useful for long-running agent tasks with tool execution.

Request Body

Same as synchronous chat.

Response (202 Accepted)

jsonCopy
{
  "job_id": "job-uuid-here",
  "status": "pending"
}

Poll the job status or use webhooks to get notified when the response is ready.

---

Audio Chat

POST /api/v1/agents/:id/chat/audio

Send an audio file as a message. The audio is transcribed via STT and then processed by the agent.

Request

Content-Type: multipart/form-data

---

Text-to-Speech

POST /api/v1/agents/:id/chat/tts

Generates an audio response from text using the configured TTS voice.

Request Body

Response

Returns audio binary with Content-Type: audio/mpeg.

---

Agent Status

GET /api/v1/agents/:id/status

Returns the current runtime status of the agent.

jsonCopy
{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "published",
  "is_online": true,
  "active_conversations": 3
}

---

Sub-Agents

Sub-agents allow an agent to delegate specific tasks to specialized child agents. There are two types:

• Template sub-agents: Attached from existing agents in the system
• Direct sub-agents: Created inline, specific to the parent agent

List Sub-Agents

GET /api/v1/agents/:id/sub-agents

jsonCopy
{
  "data": [
    {
      "id": "sub-uuid-1",
      "name": "Billing Assistant",
      "relationship_type": "template",
      "is_enabled": true,
      "delegation_prompt": "Handle all billing and payment questions"
    },
    {
      "id": "sub-uuid-2",
      "name": "Technical Support",
      "relationship_type": "direct",
      "is_enabled": true,
      "delegation_prompt": "Handle technical troubleshooting"
    }
  ]
}

Attach Sub-Agent from Template

POST /api/v1/agents/:id/sub-agents/attach

jsonCopy
{
  "agent_id": "existing-agent-uuid",
  "delegation_prompt": "Handle billing questions",
  "is_enabled": true
}

Create Direct Sub-Agent

POST /api/v1/agents/:id/sub-agents/direct

jsonCopy
{
  "name": "FAQ Bot",
  "primary_model": "gpt-3.5-turbo",
  "system_prompt": "You answer frequently asked questions.",
  "delegation_prompt": "Handle simple FAQ inquiries",
  "temperature": 0.3
}

Update Direct Sub-Agent

PUT /api/v1/agents/:id/sub-agents/direct/:subId

Update Sub-Agent Config

PATCH /api/v1/agents/:id/sub-agents/:subId

jsonCopy
{
  "delegation_prompt": "Updated delegation instructions",
  "is_enabled": false
}

Detach Sub-Agent

DELETE /api/v1/agents/:id/sub-agents/:subId

Returns 204 No Content.

---

Train Agent

POST /api/v1/agents/:id/train

Triggers training (document indexing into the RAG knowledge base). Upload documents first via the Storage API, then reference them here.

Request (multipart/form-data)

Response

jsonCopy
{
  "status": "training",
  "document_count": 3,
  "message": "Training started. Documents are being processed."
}

Training runs asynchronously. Check agent status or logs to monitor progress.

---

Agent Stats

GET /api/v1/agents/:id/stats

Response

jsonCopy
{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "total_conversations": 1520,
  "total_messages": 8432,
  "total_tokens_used": 2450000,
  "avg_response_time_ms": 1850,
  "period": "all_time"
}

---

Agent Logs

GET /api/v1/agents/:id/logs

Returns chat interaction logs for debugging and monitoring.

Query Parameters

Log Settings

GET /api/v1/agents/:id/log-settings
PUT /api/v1/agents/:id/log-settings

Configure what gets logged (messages, tool calls, token usage, etc.).

jsonCopy
{
  "log_messages": true,
  "log_tool_calls": true,
  "log_token_usage": true,
  "retention_days": 30
}

---

SerpAPI (Web Search)

Give an agent the ability to search the web via SerpAPI integration.

Get Search Config

GET /api/v1/agents/:id/serpapi/config

jsonCopy
{
  "enabled": true,
  "search_engine": "google",
  "max_results": 5,
  "safe_search": true
}

Update Search Config

PUT /api/v1/agents/:id/serpapi/config

jsonCopy
{
  "max_results": 10,
  "safe_search": false
}

Enable / Disable

bashCopy
# Enable
curl -X POST "https://your-instance.arcanflows.com/api/v1/agents/AGENT_ID/serpapi/enable" \
  -H "Authorization: Bearer <your_login_jwt>"

# Disable
curl -X POST "https://your-instance.arcanflows.com/api/v1/agents/AGENT_ID/serpapi/disable" \
  -H "Authorization: Bearer <your_login_jwt>"

---

Public Embed

GET /api/v1/public/agents/:id/embed

Returns an embeddable script tag for adding a chat widget to any website.

Response

jsonCopy
{
  "embed_code": "<script src=\"https://your-instance.arcanflows.com/embed/AGENT_ID.js\" async></script>",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "agent_name": "Support Bot"
}

---

Full Example: Create, Configure, and Chat

bashCopy
# 1. Create the agent
AGENT_ID=$(curl -s -X POST "https://your-instance.arcanflows.com/api/v1/agents" \
  -H "Authorization: Bearer <your_login_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Assistant",
    "primary_model": "claude-3.5-sonnet",
    "system_prompt": "You help customers learn about our products.",
    "temperature": 0.6
  }' | jq -r '.id')

# 2. Enable web search
curl -X POST "https://your-instance.arcanflows.com/api/v1/agents/$AGENT_ID/serpapi/enable" \
  -H "Authorization: Bearer <your_login_jwt>"

# 3. Publish the agent
curl -X PUT "https://your-instance.arcanflows.com/api/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer <your_login_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"status": "published"}'

# 4. Chat
curl -X POST "https://your-instance.arcanflows.com/api/v1/agents/$AGENT_ID/chat" \
  -H "Authorization: Bearer <your_login_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your top products this year?"}'