> For the complete documentation index, see [llms.txt](https://docs.iynxdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iynxdev.com/addon-api/getting-started/rest-api.md).

# Rest API

This page explains how to create and use custom HTTP API routes for your AthenaBot plugin.

***

## Running API calls

```js
const result = await axios.get('https://<web_api_base_ip>/api/status', {
  headers: { Authorization: '<web_api_auth_key>' }
});
```

Depending on the restrictions configured for each API route, the IP address of the incoming request may need to be whitelisted in your Web API configuration.

***

## Adding custom API routes

### 1. Setting up the route file

* Create a new route file inside your plugin directory: `/plugins/<plugin_name>/src/routes/`
* The file name can be anything, but it is recommended to match the route name, such as `hello.js`.

> The Web API plugin must be enabled and running for routes to work. If the Web API plugin fails to load, is disabled, or if the plugin that owns the route is disabled, the route becomes unavailable.

### 2. Configuration options

* **name:** A unique identifier for the route.
* **path:** The endpoint path where the route will be accessible. Do not include `http://` or the domain name.
* **type:** The HTTP method the route should respond to. Available types: `get`, `post`, `put`, `delete`.
* **ip:** If enabled, all incoming requests must originate from a whitelisted IP address.
* **key:** If enabled, all incoming requests must include a valid authentication key in the request headers.

### 3. Handling requests

Each route must implement an asynchronous `execute(req, res)` method. This method is called whenever a request hits the registered endpoint. You can access:

* Request data via `req`
* Response helpers via `res`

Athena provides helper methods such as `this.generateSuccessResponse()` or `this.generateErrorResponse()` to keep API responses consistent across plugins.

### 4. Example route

The following example registers a `GET` endpoint at `/api/hello` and returns a simple JSON response.

```js
const routeManager = require('../../../web_api/src/route.js');

module.exports = class hello extends routeManager {
  constructor(heart) {
    super(heart, { name: 'hello', path: 'api/hello', type: 'get' }, { ip: false, key: false });
  }

  async execute(req, res) {
    res.status(200).send(this.generateSuccessResponse({ message: 'Hello world!' }));
  }
};
```