Endpoints

Every verified endpoint on the OpenShield agent metrics API and the XDP.NETWORK console REST API, with curl examples for common tasks.

Last updated

On this page

Two APIs are documented here: the agent metrics API on your server, and the console REST API behind the dashboard. Only the endpoints listed below are verified — treat anything else as unlisted and subject to change.

Agent metrics API endpoints

Base URL: the metrics address printed by openshield key. Auth: Authorization: Bearer osk_... on every request.

MethodPathPurpose
GET/healthLiveness check; also verifies the key
GET/metricsFull JSON snapshot of the agent's state

Console REST API endpoints

Base URL: the same host as the dashboard ($CONSOLE in the examples). Auth: the pl_session cookie from login, except where marked public.

MethodPathPurpose
POST/api/auth/loginLog in; sets pl_session
POST/api/auth/registerCreate an account
POST/api/auth/logoutEnd the session
GET/api/catalogPublic product catalog
GET/api/productsProducts on your account
GET/api/serversList your servers
POST/api/serversAdd a server
POST/api/servers/testReachability check against an agent's /health
GET/api/servers/:idOne server's details
DELETE/api/servers/:idRemove a server
GET/api/servers/:id/metricsServer-side proxy to the agent's /metrics
GET/POST/DELETE/api/servers/:id/control?path=<path>Proxied agent control API (allowlisted paths)
GET/api/servers/:id/sectionOne section of a server's console data
GET/api/ticketsList support tickets
POST/api/ticketsOpen a ticket (product_id, subject, message)

Add a server via the API

POST /api/servers
curl -b cookies.txt -X POST "$CONSOLE/api/servers" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "...",
    "name": "edge-1",
    "api_url": "http://203.0.113.10:9100",
    "api_key": "osk_..."
  }'

The key is stored server-side and never sent back to browsers after saving. Call POST /api/servers/test first if you want the same reachability check the dashboard's Test connection button performs.

Read metrics through the proxy

GET /api/servers/:id/metrics calls your agent's /metrics from the console server, attaching the stored key there. You get the agent's JSON snapshot without exposing the key or the agent port to a browser. If the agent is unreachable, the proxy returns 502.

Fetch metrics for server 42
curl -b cookies.txt "$CONSOLE/api/servers/42/metrics"

Control the agent through the control proxy

GET, POST, and DELETE /api/servers/:id/control?path=<path> forward to the agent's control API. The path parameter must be on this allowlist:

config, whitelist, whitelist/clear, whitelist/import, blacklist, blacklist/clear, geo/mode, geo/toggle, baseline/export, baseline/import, baseline/delete, autofetch/toggle, autofetch/never-add, autofetch/never-remove, autofetch/fetch-now, schedule, block-pattern, attacks, attacks/blacklist, attacks/blacklist/status

Anything else returns 400 with unknown control path. GET requires the control read permission; mutations (POST, DELETE) require edit.

Read the running config via the proxy
curl -b cookies.txt "$CONSOLE/api/servers/42/control?path=config"

Next steps