> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orkeia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Agent

> Executes an action associated with the agent.

## Endpoint

`POST https://gateway.orkeia.ai/agents/{id}/execute`

## Headers

```
authorization:  <your_token>
Content-Type: application/json
```

### Path Parameters

You must pass the agent id via query params

```json theme={null}
{
  "id": "Agent ID (required)"
}
```

### Request body

```json theme={null}
{
  "agent": "agent id",
  "input": "prompt",
  "context": [{
    "role": ["user","assistant"],
    "content": "context content"
  }],
  "chatId": "chat id, if any",
  "files": "array of files, if any",
  "metadata": Metadata,
}
```

<Tip>
  This request is our AgentPayload! If you have any questions about it, we recommend checking out this [link](https://docs.orkeia.ai/pt-BR/core-concepts/agents/payload).
</Tip>

### Example (cURL)

```bash theme={null}
curl -X POST "https://gateway.orkeia.ai/agents/agent123/execute" \
  -H "authorization:  <your_token>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "process"}'
```

## Responses

### Response - Success

```json response theme={null}
{
  "status": "OK",
  "data": { 
	"response" : "processing result", 
    "chatId": "chat id", 
    "file": "file path, if any"}
   }
}
```

### 500 — Bad Request

```json theme={null}
{
  "status": "ERROR",
  "code": "server/error",
  "data": null
}
```

### 400 — Client Error

```json theme={null}
{
  "status": "ERROR",
  "code": "client/error",
  "data": null
}
```