Agent API Reference

Base URL: https://api.agenticflow.ai/

Paths in this guide use the external prefix v1. For self‑hosted/dev, the API prefix is api (for example, /api/agents/...).

This page documents listing, managing, streaming, publishing, and triggering Agents for API‑key clients. Payloads are specified with explicit JSON Schemas to align with common industry conventions.

Authentication

All requests require an API key. Find your Workspace ID and API key at: https://agenticflow.ai/app/workspaces/{WORKSPACE_ID}/settings/api-keys

Header: Authorization: Bearer {API_KEY}

Python example:

headers = {"Authorization": f"Bearer {api_key}"}

Scoping & Permissions

Agents are project‑scoped. Your API key can only access agents in its assigned project.
Workflows are project‑scoped; you cannot attach tools from other projects.
Knowledge datasets are project‑scoped.
Sub‑agents are validated against agent/project scope.

Requests that violate scope return 403 Forbidden.

Agents

Agent (Response)

Represents an agent resource.

JSON Schema (simplified):

{
  "type": "object",
  "required": ["id", "workspace_id", "name", "visibility", "model", "tools", "plugins", "sub_agents", "created_at", "updated_at"],
  "properties": {
    "id": {"type": "string", "format": "uuid"},
    "workspace_id": {"type": "string", "format": "uuid"},
    "project_id": {"type": ["string", "null"]},
    "user_id": {"type": ["string", "null"]},
    "name": {"type": "string"},
    "description": {"type": ["string", "null"]},
    "visibility": {"type": "string", "enum": ["private", "public"]},
    "model": {"type": "string"},
    "system_prompt": {"type": ["string", "null"]},
    "model_user_config": {
      "type": ["object", "null"],
      "properties": {
        "temperature": {"type": "number", "minimum": 0, "maximum": 1},
        "max_tokens": {"type": ["integer", "null"], "maximum": 50000},
        "max_input_tokens": {"type": ["integer", "null"], "maximum": 3000000}
      },
      "additionalProperties": false
    },
    "tools": {"type": "array"},
    "plugins": {"type": "array"},
    "sub_agents": {"type": "array"},
    "suggest_replies": {"type": "boolean"},
    "suggest_replies_model": {"type": ["string", "null"]},
    "suggest_replies_model_user_config": {"type": ["object", "null"]},
    "suggest_replies_prompt_template": {"type": ["string", "null"]},
    "auto_generate_title": {"type": "boolean"},
    "welcome_message": {"type": "string"},
    "suggested_messages": {"type": "array"},
    "agent_metadata": {"type": "object"},
    "knowledge": {"type": ["object", "null"]},
    "task_management_config": {"type": ["object", "null"]},
    "file_system_tool_config": {"type": ["object", "null"]},
    "response_format": {"type": ["object", "null"]},
    "skills_config": {"type": ["object", "null"]},
    "recursion_limit": {"type": ["integer", "null"], "minimum": 11, "maximum": 99},
    "created_at": {"type": "string"},
    "updated_at": {"type": "string"}
  },
  "additionalProperties": true
}

List Agents

GET /v1/agents?workspace_id={workspace_id}[&project_id=...&limit=...&offset=...&search_query=...]

Query:
- workspace_id (UUID, required)
- project_id (string, optional)
- limit (integer, default 100)
- offset (integer, default 0)
- search_query (string, optional)

curl -X GET "https://api.agenticflow.ai/v1/agents?workspace_id={WORKSPACE_ID}&limit=50" \
  -H "Authorization: Bearer $API_KEY"

Get Agent

GET /v1/agents/{agent_id}

curl -X GET "https://api.agenticflow.ai/v1/agents/{agent_id}" \
  -H "Authorization: Bearer $API_KEY"

Create Agent

POST /v1/agents?workspace_id={workspace_id}

Query: workspace_id (UUID, required)
Body: CreateAgentRequest (schema below)

CreateAgentRequest schema:

{
  "type": "object",
  "required": ["name", "project_id", "tools"],
  "properties": {
    "name": {"type": "string"},
    "project_id": {"type": "string"},
    "description": {"type": ["string", "null"]},
    "visibility": {"type": "string", "enum": ["private", "public"], "default": "private"},
    "model": {"type": ["string", "null"], "default": "agenticflow/gpt-4o-mini"},
    "system_prompt": {"type": ["string", "null"]},
    "model_user_config": {
      "type": ["object", "null"],
      "properties": {
        "temperature": {"type": "number", "minimum": 0, "maximum": 1},
        "max_tokens": {"type": ["integer", "null"], "maximum": 50000},
        "max_input_tokens": {"type": ["integer", "null"], "maximum": 3000000}
      },
      "additionalProperties": false
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["workflow_id"],
        "properties": {
          "run_behavior": {"type": "string", "enum": ["auto_run", "request_confirmation"], "default": "auto_run"},
          "workflow_id": {"type": "string", "format": "uuid"},
          "description": {"type": ["string", "null"]},
          "timeout": {"type": "integer", "minimum": 1, "maximum": 300, "default": 150},
          "input_config": {"type": ["object", "null"]}
        },
        "additionalProperties": false
      }
    },
    "plugins": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["plugin_id", "plugin_version"],
        "properties": {
          "plugin_id": {"type": "string"},
          "plugin_version": {"type": "string"},
          "run_behavior": {"type": "string", "enum": ["auto_run", "request_confirmation"], "default": "auto_run"},
          "connection": {"type": ["string", "null"]},
          "input_config": {
            "type": ["object", "null"],
            "additionalProperties": {
              "type": "object",
              "required": ["value"],
              "properties": {
                "value": {},
                "description": {"type": ["string", "null"]}
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      }
    },
    "sub_agents": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["sub_agent_id", "description"],
        "properties": {
          "sub_agent_id": {"type": "string", "format": "uuid"},
          "description": {"type": "string"},
          "meta": {"type": ["object", "null"]}
        },
        "additionalProperties": false
      }
    },
    "suggest_replies": {"type": "boolean", "default": true},
    "suggest_replies_model": {"type": ["string", "null"]},
    "suggest_replies_model_user_config": {"type": ["object", "null"]},
    "suggest_replies_prompt_template": {"type": ["string", "null"]},
    "auto_generate_title": {"type": "boolean", "default": true},
    "welcome_message": {"type": "string", "default": "Hello, how can I help you today?"},
    "suggested_messages": {
      "type": "array",
      "maxItems": 4,
      "items": {
        "type": "object",
        "required": ["title", "label", "action"],
        "properties": {
          "title": {"type": "string"},
          "label": {"type": "string"},
          "action": {"type": "string"}
        },
        "additionalProperties": false
      }
    },
    "agent_metadata": {"type": "object", "default": {}},
    "mcp_clients": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["mcp_client_id"],
        "properties": {
          "mcp_client_id": {"type": "string", "format": "uuid"},
          "run_behavior": {"type": "string", "enum": ["auto_run", "request_confirmation"], "default": "auto_run"},
          "description": {"type": ["string", "null"]},
          "timeout": {"type": "integer", "minimum": 1, "maximum": 300, "default": 150},
          "tools": {
            "type": ["object", "null"],
            "additionalProperties": {
              "type": "object",
              "properties": {"allowed": {"type": "boolean", "default": true}},
              "required": ["allowed"],
              "additionalProperties": false
            }
          },
          "override_headers": {"type": ["object", "null"], "additionalProperties": {"type": "string"}}
        },
        "additionalProperties": false
      }
    },
    "knowledge": {"type": ["object", "null"]},
    "task_management_config": {"type": ["object", "null"]},
    "file_system_tool_config": {"type": ["object", "null"]},
    "response_format": {"type": ["object", "null"]},
    "skills_config": {"type": ["object", "null"]},
    "recursion_limit": {"type": ["integer", "null"], "minimum": 11, "maximum": 99}
  },
  "additionalProperties": false
}

Minimal example:

{ "name": "Support Bot", "project_id": "YOUR_PROJECT_ID", "tools": [] }

curl -X POST "https://api.agenticflow.ai/v1/agents?workspace_id={WORKSPACE_ID}" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support Bot","project_id":"YOUR_PROJECT_ID","tools":[]}'

Update Agent

PUT /v1/agents/{agent_id}

Body: UpdateAgentRequest (any subset of CreateAgentRequest fields)

UpdateAgentRequest schema:

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "description": {"type": ["string", "null"]},
    "visibility": {"type": "string", "enum": ["private", "public"]},
    "model": {"type": "string"},
    "system_prompt": {"type": "string"},
    "model_user_config": {"type": "object"},
    "tools": {"type": "array"},
    "plugins": {"type": "array"},
    "sub_agents": {"type": "array"},
    "mcp_clients": {"type": "array"},
    "suggest_replies": {"type": "boolean"},
    "suggest_replies_model": {"type": "string"},
    "suggest_replies_model_user_config": {"type": "object"},
    "suggest_replies_prompt_template": {"type": "string"},
    "suggested_messages": {"type": "array"},
    "agent_metadata": {"type": "object"},
    "welcome_message": {"type": "string"},
    "knowledge": {"type": "object"},
    "task_management_config": {"type": "object"},
    "file_system_tool_config": {"type": "object"},
    "response_format": {"type": "object"},
    "skills_config": {"type": "object"},
    "recursion_limit": {"type": "integer", "minimum": 11, "maximum": 99}
  },
  "additionalProperties": false
}

Example:

{ "name": "Support Pro Bot", "visibility": "public" }

Delete Agent

DELETE /v1/agents/{agent_id}

Stream Messages (Vercel AI SDK – Data Stream v1)

POST /v1/agents/{agent_id}/stream

Headers:
- Authorization: Bearer {API_KEY}
- Content-Type: application/json
- Optional: x-enable-request-context: true
Body: StreamRequest (compatible with AI SDK message shape). Only the last message is used. Include a stable id to thread conversations.

StreamRequest schema (minimal):

{
  "type": "object",
  "required": ["id", "messages"],
  "properties": {
    "id": {"type": "string"},
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {"type": "string", "enum": ["system", "user", "assistant", "data"]},
          "content": {"type": "string"},
          "experimental_attachments": {
            "type": ["array", "null"],
            "items": {"type": "object", "properties": {"url": {"type": "string"}}, "required": ["url"], "additionalProperties": true}
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": false
}

Text example:

{ "id": "847c6285-8fc9-4560-a83f-4e6285809254", "messages": [{"role": "user", "content": "Write a haiku about the ocean."}] }

With image attachments:

{
  "id": "847c6285-8fc9-4560-a83f-4e6285809254",
  "messages": [{
    "role": "user",
    "content": "Describe this image.",
    "experimental_attachments": [{"url": "https://example.com/cat.jpg"}]
  }]
}

Response headers:

Content-Type: text/plain; charset=utf-8
x-vercel-ai-data-stream: v1

Line‑delimited stream prefixes:

0: text delta
g: reasoning delta (JSON)
2: data part (JSON array)
9: tool call (JSON)
a: tool result (JSON or string)
f: start step (JSON)
e: finish step (JSON)
d: finish message (JSON)
3: error (JSON)

Anonymous streaming for public agents:

POST /v1/agents/anonymous/{agent_id}/stream

Public Agent Info

GET /v1/agents/anonymous/{agent_id}

Returns: id, name, description, auto_generate_title, welcome_message, suggested_messages, agent_metadata, suggest_replies.

Webhook Triggers

Create, manage, and invoke webhooks that send messages to an agent.

POST /v1/agents/{agent_id}/triggers
GET /v1/agents/{agent_id}/triggers
GET /v1/agents/triggers/{trigger_id}
PUT /v1/agents/triggers/{trigger_id}
DELETE /v1/agents/triggers/{trigger_id}
GET /v1/agents/{agent_id}/triggers/{trigger_id}/events?limit=...&offset=...
{METHOD} /v1/agents/webhook/{path}/trigger

Trigger create/update schema (essentials):

{
  "type": "object",
  "required": ["name", "trigger_type", "trigger_config", "task_config"],
  "properties": {
    "name": {"type": "string"},
    "description": {"type": ["string", "null"]},
    "trigger_type": {"type": "string", "enum": ["webhook"]},
    "trigger_config": {
      "type": "object",
      "required": ["auth_config", "method", "response_code"],
      "properties": {
        "auth_config": {
          "type": "object",
          "required": ["auth_type"],
          "properties": {
            "auth_type": {"type": "string", "enum": ["NONE", "BASIC", "BEARER"]},
            "username": {"type": ["string", "null"]},
            "password": {"type": ["string", "null"]},
            "token": {"type": ["string", "null"]}
          },
          "additionalProperties": false
        },
        "method": {"type": "string", "enum": ["GET", "POST", "PUT", "DELETE"]},
        "response_code": {"type": "integer"}
      },
      "additionalProperties": false
    },
    "task_config": {
      "type": "object",
      "required": ["type", "message"],
      "properties": {
        "type": {"type": "string", "enum": ["SEND_MESSAGE_TO_CHAT"]},
        "message": {"type": "string"},
        "chat_id": {"type": ["string", "null"]}
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Invoke example:

curl -X POST "https://api.agenticflow.ai/v1/agents/webhook/{path}/trigger" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer secret-token" \
  -d '{"order_id": 123, "total": 49.99}'

Notes:

The create response includes trigger_config.path (UUID). Use it in the invoke URL.
Provide the corresponding Authorization header when invoking based on auth_config.

Errors

401 Unauthorized
403 Forbidden
404 Not Found
429 Rate Limit Exceeded
500 Internal Server Error

Streaming errors surface as an 3: line and/or a final d:{"error": "..."} line.

Rate Limits

Defaults may vary by environment and plan. In self‑hosted/dev, a global limiter of ~100 requests/min/IP may be enabled. Contact support for production quotas.