# Endpoints

> Every verified endpoint on the OpenShield agent metrics API and the XDP.NETWORK console REST API, with curl examples for common tasks.
>
> Canonical: https://xdp.network/docs/api-reference/endpoints · Updated 2026-08-09

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.

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/health` | Liveness check; also verifies the key |
| GET | `/metrics` | Full 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](/docs/api-reference/authentication), except where
marked public.

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/api/auth/login` | Log in; sets `pl_session` |
| POST | `/api/auth/register` | Create an account |
| POST | `/api/auth/logout` | End the session |
| GET | `/api/catalog` | Public product catalog |
| GET | `/api/products` | Products on your account |
| GET | `/api/servers` | List your servers |
| POST | `/api/servers` | Add a server |
| POST | `/api/servers/test` | Reachability check against an agent's `/health` |
| GET | `/api/servers/:id` | One server's details |
| DELETE | `/api/servers/:id` | Remove a server |
| GET | `/api/servers/:id/metrics` | Server-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/section` | One section of a server's console data |
| GET | `/api/tickets` | List support tickets |
| POST | `/api/tickets` | Open a ticket (`product_id`, `subject`, `message`) |

## Add a server via the API

```bash title="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`.

```bash title="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.

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

## Next steps

- [Authentication](/docs/api-reference/authentication)
- [Errors](/docs/api-reference/errors)
- [Getting credentials](/docs/openshield-xdp/getting-credentials)