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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.agenticflow.ai/developers/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.