<a id="http-api"></a>

# HTTP API

This is the documentation for the [Listener directives](config_startup.html.md#api-listener), shown in the form of `curl` examples.
For the address `127.0.0.1:8090`, use your own specific host and port.

<a id="troubleshooting"></a>

## Troubleshooting

- If you see `curl: (1) Received HTTP/0.9 when not allowed`, you are probably making plain `http` requests to an `https` listener that is configured with [`listeners[].pki`](config_startup.html.md#confval-listeners-.pki).
  Adjust your request method to `https:`
- In these examples, `<ip>` and `<grouping>` are placeholders. Replace them with specific values.
- Grouping names start with a literal `&` which has special meaning in HTTP. Escape them in the request path, e.g. `%26yahooapac`.
- Dotted-decimal IP addresses are accepted in literal form. You can also encode the `.` in the request path as `%2E`.

Possible error responses
: - **400** (Bad Request): Missing parameters, invalid data, or grouping already exists.
  - **401** (Unauthorized): You have [`authentication.apikeys[]`](config_running.html.md#confval-authentication.apikeys). Pass in a valid key: `-H "X-Api-Key: badsecret"`
  - **404** (Not Found)

JSON response is in compact format; examples shown below are pretty-printed for ease of reading.

<a id="config-endpoints"></a>

## *Config* endpoints

<a id="get-all-config"></a>

### Get all config

```bash
curl http://127.0.0.1:8090/config
```

Returns all IPs and their groupings.

<a id="get-config-for-an-ip"></a>

### Get config for an IP

```bash
curl http://127.0.0.1:8090/config/<ip>
```

<a id="get-config-for-an-ip-and-grouping"></a>

### Get config for an IP and grouping

```bash
curl http://127.0.0.1:8090/config/<ip>/<grouping>
```

*example response*

```json
 {
     "end": {
         "date": "2025-09-08",
         "volume": 26396
     },
     "grouping": "&yahooapac",
     "mode": "AUTO",
     "paused": false,
     "algorithm":"TOKENBUCKET",
     "interval": 86400,
     "start": {
         "date": "2025-07-31",
         "volume": 233
     }
 }
```

<a id="add-ip-config"></a>

<a id="add-ip-to-config"></a>

### Add IP to config

```bash
curl -iX POST http://127.0.0.1:8090/config/<ip> -H "Content-Type: application/json" -d '{ ... }'
```

Returns `200` OK on success, `400` Bad Request if IP already exists or if the data is invalid.

Required keys and values for each grouping are start date and volume, end date and volume, and schedule mode.
For manual schedules an array of days and target volumes for each day is also required.

> **Tip**
> 
> Use single-quotes as shown, to surround data with `-d`, then the inner `"` don’t need to be escaped.

*example request*

```bash
 curl -iX POST http://127.0.0.1:8090/config/10.0.0.1  -H "Content-Type: application/json" -d '{
     "groupings":
     [
         {
             "grouping": "&auto_example",
             "start":
             {
                 "date": "2025-08-01",
                 "volume": 100
             },
             "end":
             {
                 "date": "2025-08-30",
                 "volume": 20000
             },
             "mode": "AUTO",
             "paused": false,
             "algorithm":"TOKENBUCKET",
             "interval": 86400,
         },
         {
             "grouping": "&manual_example",
             "start":
             {
                 "date": "2025-08-01"
             },
             "mode": "MANUAL",
             "paused": false,
             "algorithm":"TOKENBUCKET",
             "interval": 86400,
             "schedule":
             [
                 {
                     "day": 1,
                     "messages": 300
                 },
                 {
                     "day": 2,
                     "messages": 400
                 },
                 {
                     "day": 3,
                     "messages": 500
                 }
             ]
         }
     ]
 }'
```

*Success (200) response*

```json
{"status":"success"}
```

*Error (400) response*

```json
{"error":"IP already exists"}
```

<a id="update-ip-config"></a>

### Update IP config

```bash
curl -iX PUT http://127.0.0.1:8090/config/<ip> -H "Content-Type: application/json" -d '{ ... }'
```

Request data follows the same pattern as [Add IP to config](#add-ip-config) example.

Returns `200` OK on success, `400` Bad Request on validation errors, `404` if IP does not exist.

<a id="delete-ip-from-config"></a>

### Delete IP from config

```bash
curl -iX DELETE http://127.0.0.1:8090/config/<ip>
```

Returns `200` OK on success, `404` Not Found if IP does not exist.

<a id="pause-resume-all-groupings-for-an-ip"></a>

### Pause/resume all groupings for an IP

```bash
curl -iX PUT http://127.0.0.1:8090/config/<ip>/pause
curl -iX PUT http://127.0.0.1:8090/config/<ip>/resume
```

Returns `200` OK on success, `404` if IP does not exist.

<a id="pause-resume-a-grouping-within-an-ip"></a>

### Pause/resume a grouping within an IP

```bash
curl -iX PUT http://127.0.0.1:8090/config/<ip>/<grouping>/pause
curl -iX PUT http://127.0.0.1:8090/config/<ip>/<grouping>/resume
```

Returns `200` OK on success, `404` if the IP or named grouping does not exist.

<a id="delete-grouping-from-ip"></a>

### Delete grouping from IP

```bash
curl -iX DELETE http://127.0.0.1:8090/config/<ip>/<grouping>
```

Returns `200` OK on success, `404` if the IP or named grouping does not exist.

<a id="status-endpoints"></a>

## *Status* endpoints

<a id="get-all-status"></a>

### Get all status

```bash
curl http://127.0.0.1:8090/status
```

Returns the configuration and current status of every IP and grouping in the configuration.
Status indicates if the schedule is currently on track to meet the target volumes, finished, or paused.
Information about the current day in the schedule is also included.

*Success (200) response*

```json
 {
     "ips":
     {
         "10.0.0.2":
         {
             "groupings":
             [
                 {
                     "current_day": 1,
                     "end":
                     {
                         "date": "2025-08-03",
                         "volume": 30000
                     },
                     "mode": "MANUAL",
                     "paused": false,
                     "algorithm":"TOKENBUCKET",
                     "interval": 86400,
                     "properties": null,
                     "schedule":
                     [
                         {
                             "date": "2025-08-01",
                             "day": 1,
                             "messages": 500
                         },
                         {
                             "date": "2025-08-02",
                             "day": 2,
                             "messages": 600
                         },
                         {
                             "date": "2025-08-03",
                             "day": 3,
                             "messages": 30000
                         }
                     ],
                     "start":
                     {
                         "date": "2025-08-01",
                         "volume": 500
                     },
                     "status": "ONSCHEDULE"
                 }
             ]
         }
     }
 }
```

<a id="get-status-for-an-ip"></a>

### Get status for an IP

```bash
curl http://127.0.0.1:8090/status/<ip>
```

This returns the data for a single IP, e.g.

*Success (200) response*

```json
 {
     "groupings":
     [
         {
             "current_day": 1,
             "end":
             {
                 "date": "2025-08-03",
                 "volume": 30000
             },
             "grouping": "&manual_example",
             "mode": "MANUAL",
             "paused": false,
             "algorithm":"TOKENBUCKET",
             "interval": 86400,
             "properties": null,
             "schedule":
             [
                 {
                     "date": "2025-08-01",
                     "day": 1,
                     "messages": 500
                 },
                 {
                     "date": "2025-08-02",
                     "day": 2,
                     "messages": 600
                 },
                 {
                     "date": "2025-08-03",
                     "day": 3,
                     "messages": 30000
                 }
             ],
             "start":
             {
                 "date": "2025-08-01",
                 "volume": 500
             },
             "status": "ONSCHEDULE"
         }
     ],
     "timezone_offset": 0
 }
```

<a id="get-status-for-an-ip-and-grouping"></a>

### Get status for an IP and grouping

```bash
curl http://127.0.0.1:8090/status/<ip>/<grouping>
```

*Success (200) response*

```json
 {
     "current_day": 1,
     "end":
     {
         "date": "2025-08-03",
         "volume": 30000
     },
     "mode": "MANUAL",
     "paused": false,
     "properties": null,
     "algorithm":"TOKENBUCKET",
     "interval": 86400,
     "schedule":
     [
         {
             "date": "2025-08-01",
             "day": 1,
             "messages": 500
         },
         {
             "date": "2025-08-02",
             "day": 2,
             "messages": 600
         },
         {
             "date": "2025-08-03",
             "day": 3,
             "messages": 30000
         }
     ],
     "start":
     {
         "date": "2025-08-01",
         "volume": 500
     },
     "status": "ONSCHEDULE"
 }
```