# Call an agent API

The **Call an Agent** endpoint allows you to interact with an Aicado agent programmatically. You can send user input, optional instructions, and receive a response either synchronously or asynchronously.

***

## Endpoint

```http
POST https://run.aicado.ai/api/1.1/wf/call-an-agent/
```

***

## Authentication

All requests must include an **Authorization** header with a Bearer token.

```http
Authorization: Bearer <your_access_token>
```

You can get your access token from Settings section.

<figure><img src="/files/YE6g0QqnVcFyeawttH4t" alt=""><figcaption></figcaption></figure>

***

## Request Body

The request must be sent as JSON.

```json
{
  "agent_id": "<agent_id>",
  "instructions": "<instructions>",
  "user_input": "<user_input>",
  "response_webhook_url": ""
}
```

***

## Parameters

| Field                  | Type   | Required | Description                                                                                                                                         |
| ---------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`             | String | Yes      | The unique identifier of the Aicado agent.                                                                                                          |
| `instructions`         | String | No       | Additional context or instructions for the agent. If you don't fill this field, the agent instructions comes from agent editor -> settings section. |
| `user_input`           | String | Yes      | The user’s input (e.g., text query, request, or command).                                                                                           |
| `response_webhook_url` | String | No       | Optional webhook URL for asynchronous responses. Leave empty for sync mode.                                                                         |

***

## Example Request

```http
POST https://run.aicado.ai/api/1.1/wf/call-an-agent/
Content-Type: application/json
Authorization: Bearer bus|1751539548390x38855731272
```

**Body:**

```json
{
  "agent_id": "1756206481771x7072709",
  "instructions": "Provide a concise summary of the input.",
  "user_input": "10x10 wooden frame",
  "response_webhook_url": ""
}
```

***

## Example Response

```json
{
  "call": {
    "call_id": "1749027897108x743874372478867000",
    "call_status": "success",
    "call_error": null,
    "creation_date": 1749027897114,
    "completion_date": 1749027897143
  },
  "tool": {
    "tool_status": "",
    "tool_name": "",
    "tool_error": null
  },
  "agent": {
    "agent_id": "1749023792510x127939515425357090",
    "agent_status": "completed",
    "agent_output": "{\\"a_points\\": 0, \\"r_points\\": 0, \\"t_points\\": 0, \\"i_points\\": 0, \\"a_report\\": \\"No input provided for analysis.\\", \\"r_report\\": \\"No data to assess for relevance.\\", \\"t_report\\": \\"No testable information supplied.\\", \\"i_report\\": \\"No item to interpret.\\"}"
  },
  "usage": {
    "agent_expense": 0.28734,
    "tool_expense": null,
    "total_expense": 0.28734
  },
  "credit": 643.758554,
  "error": null
}

```

***

## Error Handling

If the request fails, the API will return an error object:

```json
{
  "status": "error",
  "message": "Invalid agent_id"
}
```

⚡ Notes

* Always include a valid `Authorization` header.
* If `response_webhook_url` is provided, the agent response will be sent asynchronously.
* Ensure the `agent_id` exists and is valid.

## Structured Outputs

The **Call an Agent** endpoint also supports **Structured Outputs**.\
This allows you to define the format of the response returned by the agent.

***

### How it Works

You can specify the output format in two ways:

1. **From the editor** – Define the schema visually in the editor.
2. **Via API request** – Send the schema in the request body as a `"text"` value.

In both cases, the schema should always be sent in a **minified JSON format**, for more details check [this page](/creating-ai-agent/settings.md#structured-outputs)

***


---

# 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.aicado.ai/for-developers/call-an-agent-api.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.