# Agent API

{% hint style="warning" %}
The Agent API is currently in Beta - Please report any issues or feedback in our [Telegram Group](https://t.me/+KCMjT02DBX84Zjkx)
{% endhint %}

***

## About

The Agent API is the next evolution of Katoshi - Allowing you to send complex commands to your AI Agents using natural language via simple POST requests or using webhooks. \
\
**Read more about agent capabilities here:**

{% content-ref url="../app/agents" %}
[agents](https://katoshi.gitbook.io/katoshi-docs/app/agents)
{% endcontent-ref %}

***

## Quick Start

<mark style="color:green;">`POST`</mark> `https://api.katoshi.ai/agent?id=USER_ID`

Replace `USER_ID` with your unique ID, which can be found in the [Settings Page](https://katoshi.ai/app?view=settings)

### Headers

| Name                                             | Type   | Description        |
| ------------------------------------------------ | ------ | ------------------ |
| `Content-Type`<mark style="color:red;">\*</mark> | String | `application/json` |

### Request Body

| Name                                           | Type   | Description                |
| ---------------------------------------------- | ------ | -------------------------- |
| `api_key`<mark style="color:red;">\*</mark>    | String | Katoshi API Key            |
| `agent_id`<mark style="color:red;">\*</mark>   | Number | ID of your agent           |
| `message`<mark style="color:yellow;">\*</mark> | String | Message sent to your agent |
| `task_id`                                      | Number | ID of a task               |

{% hint style="info" %}
The `message` field is required if no `task_id` is specified
{% endhint %}

### Example Request

```json
{
  "message": "Long BTC with $11 if the 15m RSI is oversold",
  "api_key": "12345678-1234-1234-1234-123456789012",
  "agent_id": 7
}
```

{% hint style="info" %}
For [TradingView](https://katoshi.gitbook.io/katoshi-docs/integrations/tradingview), add the Request JSON directly in the alert message field.
{% endhint %}

***

## task\_id

Passing a task\_id parameter allows you to send predefined messages to your agent.&#x20;

* Create tasks in your agent settings first, then reference the task\_id in your request.

### Example Scenario

#### Task message

```
Open a long position with $50 size, 1% stop loss, and 3% take profit when the following conditions are met:
- The 15m RSI is oversold
- The funding rates is negative
- There is no other open perpetual positions in my account
```

#### Request

```json
{
  "message": "Apply this strategy for BTC:",
  "api_key": "12345678-1234-1234-1234-123456789012",
  "agent_id": 7,
  "task_id": 2
}
```

#### Final Message

```
Apply this strategy for BTC:

Open a long position with $50 size, 1% stop loss, and 3% take profit when the following conditions are met:
- The 15m RSI is oversold
- The funding rates is negative
- There is no other open perpetual positions in my account
```

{% hint style="info" %}
The `message` parameter is optional when using `task_id`; but can be included to append it to the task message to create dynamic reuests.&#x20;
{% endhint %}

***

## Testing

Test your commands using the Agents chat interface in Katoshi.

{% hint style="info" %}
Results can vary tremendously based on your selected LLM model, system prompt, and message sent.&#x20;
{% endhint %}

{% content-ref url="../app/agents" %}
[agents](https://katoshi.gitbook.io/katoshi-docs/app/agents)
{% endcontent-ref %}
