Basic Usage

The API is served at https://surfmeter-server.<your-host>/client_admin_api/v1 and always uses JSON. (The client_admin_api path prefix is a historical Rails namespace; it remains the stable public URL.)

Authentication

All API requests must include a Surfmeter API key in the X-API-KEY header.

To create a key, log into the Surfmeter Dashboard and open Keys → Surfmeter API Keys. Each key inherits the role of the user who created it, so the permissions applied to your requests match what that user can do in the dashboard. Keys can be revoked at any time from the same page.

Example:

GET /client_admin_api/v1/clients HTTP/1.1
Host: surfmeter-server.your-customer-name.aveq.info
X-API-KEY: client_admin-...

Pagination

Endpoints that return collections accept page and per_page query parameters. The default page size varies per resource and the maximum page size is typically 1000. Paginated responses include a top-level meta object with current_page, total_pages, and total_count.

Errors

Failed requests return a JSON body with a message field describing the error in human-readable form. Validation errors (HTTP 422) additionally include a structured errors object mapping field names to lists of error messages. Authentication failures return HTTP 401, authorization failures HTTP 403, and unknown resources HTTP 404.

See the individual endpoint pages under Endpoints for the full reference. The complete OpenAPI 3.1 spec is also available as a single YAML file at /assets/openapi/surfmeter_api-v1.yml for use with OpenAPI tooling (Postman, code generators, etc.).