# 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:

```python
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):

```json
{
  "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)

```bash
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}`

```bash
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:

```json
{
  "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:

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

```bash
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:

```json
{
  "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:

```json
{ "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):

```json
{
  "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:

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

With image attachments:

```json
{
  "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):

```json
{
  "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:

```bash
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.

***

## See Also

* API Keys & Authorization: `https://agenticflow.ai/app/workspaces/{WORKSPACE_ID}/settings/api-keys`
* Support: `mailto:support@agenticflow.ai`