6. HTTP API
This is the documentation for the Listener directives, shown in the form of curl examples.
For the address 127.0.0.1:8090, use your own specific host and port.
6.1. Troubleshooting
If you see
curl: (1) Received HTTP/0.9 when not allowed, you are probably making plainhttprequests to anhttpslistener that is configured withlisteners[].pki. Adjust your request method tohttps: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[]. 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.
6.2. Config endpoints
6.2.1. Get all config
curl http://127.0.0.1:8090/config
Returns all IPs and their groupings.
6.2.2. Get config for an IP
curl http://127.0.0.1:8090/config/<ip>
6.2.3. Get config for an IP and grouping
curl http://127.0.0.1:8090/config/<ip>/<grouping>
{
"end": {
"date": "2025-09-08",
"volume": 26396
},
"grouping": "&yahooapac",
"mode": "AUTO",
"paused": false,
"start": {
"date": "2025-07-31",
"volume": 233
}
}
6.2.4. Add IP to config
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.
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
},
{
"grouping": "&manual_example",
"start":
{
"date": "2025-08-01"
},
"mode": "MANUAL",
"paused": false,
"schedule":
[
{
"day": 1,
"messages": 300
},
{
"day": 2,
"messages": 400
},
{
"day": 3,
"messages": 500
}
]
}
]
}'
{"status":"success"}
{"error":"IP already exists"}
6.2.5. Update IP config
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 example.
Returns 200 OK on success, 400 Bad Request on validation errors, 404 if IP does not exist.
6.2.6. Delete IP from config
curl -iX DELETE http://127.0.0.1:8090/config/<ip>
Returns 200 OK on success, 404 Not Found if IP does not exist.
6.2.7. Pause/resume all groupings for an IP
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.
6.2.8. Pause/resume a grouping within an IP
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.
6.2.9. Delete grouping from IP
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.
6.3. Status endpoints
6.3.1. Get all status
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.
{
"ips":
{
"10.0.0.2":
{
"groupings":
[
{
"current_day": 1,
"end":
{
"date": "2025-08-03",
"volume": 30000
},
"mode": "MANUAL",
"paused": false,
"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"
}
]
}
}
}
6.3.2. Get status for an IP
curl http://127.0.0.1:8090/status/<ip>
This returns the data for a single IP, e.g.
{
"groupings":
[
{
"current_day": 1,
"end":
{
"date": "2025-08-03",
"volume": 30000
},
"grouping": "&manual_example",
"mode": "MANUAL",
"paused": false,
"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
}
6.3.3. Get status for an IP and grouping
curl http://127.0.0.1:8090/status/<ip>/<grouping>
{
"current_day": 1,
"end":
{
"date": "2025-08-03",
"volume": 30000
},
"mode": "MANUAL",
"paused": false,
"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"
}