API reference
BlankTrail Proxy exposes a local HTTP API so you can open ports, configure identities, and automate everything the dashboard does. This page covers the base URL, authentication and conventions.
Base URL
All endpoints live under the /api/v1 prefix on the same host and port as the dashboard:
http://127.0.0.1:8891/api/v1The API and dashboard share one origin, so calls from your own scripts and tools work out of the box.
Authentication
The API is deny-by-default: almost every endpoint requires authentication. There are two ways to authenticate:
- API key — send it in the X-API-Key header. Best for scripts and automation.
- Session cookie — obtained by signing in; used by the browser dashboard.
Find and rotate your API key in the dashboard's Settings dialog. Send it on every request:
curl -H "X-API-Key: YOUR_API_KEY" http://127.0.0.1:8891/api/v1/statusImportantThe API key grants full control of your ports. Keep it secret, and restrict network access to the dashboard port (bind to localhost or use an SSH tunnel on servers).
Conventions
- Requests and responses are JSON. Send Content-Type: application/json on requests with a body.
- Configuration is always sent in the JSON body, never in query strings.
- The API is versioned under /api/v1. Breaking changes would move to a new version prefix.
Status codes
| Code | Meaning |
|---|---|
| 200 OK | Success. |
| 202 Accepted | Accepted and processing (e.g. an update was triggered). |
| 400 Bad Request | Invalid input, a missing field, or a bad value. |
| 401 Unauthorized | Authentication is required and was missing or invalid. |
| 404 Not Found | The resource doesn't exist (e.g. the port isn't open). |
| 409 Conflict | A conflict — for example the port is already open, or a gateway is in use. |
| 429 Too Many Requests | Rate-limited; slow down and retry. |
| 500 Internal Server Error | An unexpected error. |
Reference by topic
- Ports & traffic — open, close, list and configure ports; test an upstream.
- Profiles & routing — identities, presets, domain rules and gateways.
- Port Pool — open and manage pools of ports from a proxy list.
- License & access — license status, authentication, and the CA certificate.