Clients¶
Reference for the clients endpoints of the Surfmeter API.
Surfmeter API – Clients v1¶
The Surfmeter API lets you manage clients, users, capabilities, measurements, and organization-wide settings programmatically.
Servers¶
| Description | URL |
|---|---|
| https://surfmeter-server.{host}/client_admin_api/v1 | https://surfmeter-server.{host}/client_admin_api/v1 |
Clients¶
GET /clients¶
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
ApiKeyAuth |
header | string | N/A | No | API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys. |
Response 200 OK
{
"clients": [
{
"id": 0,
"uuid": "string",
"label": "string",
"extra_label": "string",
"tags": [
"string"
],
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z",
"disabled_at": "2026-01-15T10:30:00Z",
"disabled_reason": "string",
"last_measurement_at": "2026-01-15T10:30:00Z",
"registration_key": {
"id": 0,
"registration_key": "string",
"comment": "string",
"valid_from": "2026-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z",
"num_registrations_left": 0,
"usage_limit_days": 0
},
"client_groups": [
{
"id": 0,
"name": "string"
}
],
"current_isp_contract": {
"id": 0,
"isp_id": 0,
"isp_name": "string",
"client_id": 0,
"upload_speed": 0,
"download_speed": 0,
"monthly_price": 10.12,
"currency": "string",
"assumed_tariff": "string",
"connection_type": "string",
"name": "string",
"valid_from": "2026-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z"
}
}
]
}
Schema of the response body
{
"description": "Response for clients index action",
"type": "object",
"required": [
"clients"
],
"properties": {
"clients": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"uuid",
"created_at",
"updated_at",
"client_groups"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"extra_label": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"disabled_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"disabled_reason": {
"type": "string",
"nullable": true
},
"last_measurement_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"registration_key": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"registration_key": {
"type": "string"
},
"comment": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"num_registrations_left": {
"type": "integer",
"nullable": true
},
"usage_limit_days": {
"type": "integer",
"nullable": true
}
},
"nullable": true
},
"client_groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
},
"current_isp_contract": {
"type": "object",
"required": [
"id",
"isp_id",
"client_id",
"name",
"valid_from"
],
"properties": {
"id": {
"type": "integer"
},
"isp_id": {
"type": "integer"
},
"isp_name": {
"type": "string",
"nullable": true
},
"client_id": {
"type": "integer"
},
"upload_speed": {
"type": "integer",
"nullable": true
},
"download_speed": {
"type": "integer",
"nullable": true
},
"monthly_price": {
"type": "number",
"nullable": true
},
"currency": {
"type": "string",
"nullable": true
},
"assumed_tariff": {
"type": "string",
"nullable": true
},
"connection_type": {
"type": "string",
"nullable": true
},
"name": {
"type": "string"
},
"valid_from": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
}
},
"nullable": true
}
}
}
}
}
}
GET /clients/check_label_availability¶
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
ApiKeyAuth |
header | string | N/A | No | API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys. |
exclude_id |
query | None | No | Optional client ID (integer) or UUID (string) to exclude from the uniqueness check, typically the client currently being edited. | |
label |
query | string | No | Label to check for availability within the current data owner. Empty or whitespace-only values are treated as available. |
Response 200 OK
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the response body
{
"description": "Response for client label availability check action",
"type": "object",
"required": [
"available"
],
"properties": {
"available": {
"type": "boolean",
"description": "Whether the label is available for use"
},
"label": {
"type": "string",
"description": "The label that was checked (echoed back)"
}
}
}
GET /clients/{id}¶
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
ApiKeyAuth |
header | string | N/A | No | API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys. |
id |
path | string | No |
Response 200 OK
{
"client": {
"id": 0,
"uuid": "string",
"label": "string",
"extra_label": "string",
"tags": [
"string"
],
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z",
"disabled_at": "2026-01-15T10:30:00Z",
"disabled_reason": "string",
"last_measurement_at": "2026-01-15T10:30:00Z",
"registration_key": {
"id": 0,
"registration_key": "string",
"comment": "string",
"valid_from": "2026-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z",
"num_registrations_left": 0,
"usage_limit_days": 0
},
"client_groups": [
{
"id": 0,
"name": "string"
}
],
"current_isp_contract": {
"id": 0,
"isp_id": 0,
"isp_name": "string",
"client_id": 0,
"upload_speed": 0,
"download_speed": 0,
"monthly_price": 10.12,
"currency": "string",
"assumed_tariff": "string",
"connection_type": "string",
"name": "string",
"valid_from": "2026-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z"
}
}
}
Schema of the response body
{
"description": "Response for client show action",
"type": "object",
"required": [
"client"
],
"properties": {
"client": {
"type": "object",
"required": [
"id",
"uuid",
"created_at",
"updated_at",
"client_groups"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"extra_label": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"disabled_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"disabled_reason": {
"type": "string",
"nullable": true
},
"last_measurement_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"registration_key": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"registration_key": {
"type": "string"
},
"comment": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"num_registrations_left": {
"type": "integer",
"nullable": true
},
"usage_limit_days": {
"type": "integer",
"nullable": true
}
},
"nullable": true
},
"client_groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
},
"current_isp_contract": {
"type": "object",
"required": [
"id",
"isp_id",
"client_id",
"name",
"valid_from"
],
"properties": {
"id": {
"type": "integer"
},
"isp_id": {
"type": "integer"
},
"isp_name": {
"type": "string",
"nullable": true
},
"client_id": {
"type": "integer"
},
"upload_speed": {
"type": "integer",
"nullable": true
},
"download_speed": {
"type": "integer",
"nullable": true
},
"monthly_price": {
"type": "number",
"nullable": true
},
"currency": {
"type": "string",
"nullable": true
},
"assumed_tariff": {
"type": "string",
"nullable": true
},
"connection_type": {
"type": "string",
"nullable": true
},
"name": {
"type": "string"
},
"valid_from": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
}
},
"nullable": true
}
}
}
}
}
PUT /clients/{id}¶
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
ApiKeyAuth |
header | string | N/A | No | API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys. |
id |
path | string | No |
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the request body
{
"description": "Data for client update action",
"type": "object",
"properties": {
"label": {
"type": "string",
"nullable": true
},
"extra_label": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"client_group_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
}
}
Response 200 OK
{
"client": {
"id": 0,
"uuid": "string",
"label": "string",
"extra_label": "string",
"tags": [
"string"
],
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z",
"disabled_at": "2026-01-15T10:30:00Z",
"disabled_reason": "string",
"last_measurement_at": "2026-01-15T10:30:00Z",
"registration_key": {
"id": 0,
"registration_key": "string",
"comment": "string",
"valid_from": "2026-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z",
"num_registrations_left": 0,
"usage_limit_days": 0
},
"client_groups": [
{
"id": 0,
"name": "string"
}
]
}
}
Schema of the response body
{
"description": "Response for client update action",
"type": "object",
"required": [
"client"
],
"properties": {
"client": {
"type": "object",
"required": [
"id",
"uuid",
"created_at",
"updated_at",
"client_groups"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"extra_label": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"disabled_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"disabled_reason": {
"type": "string",
"nullable": true
},
"last_measurement_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"registration_key": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"registration_key": {
"type": "string"
},
"comment": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"num_registrations_left": {
"type": "integer",
"nullable": true
},
"usage_limit_days": {
"type": "integer",
"nullable": true
}
},
"nullable": true
},
"client_groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
}
POST /clients/{id}/disable¶
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
ApiKeyAuth |
header | string | N/A | No | API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys. |
id |
path | string | No |
Request body
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the request body
{
"description": "Data for client update action",
"type": "object",
"properties": {
"label": {
"type": "string",
"nullable": true
},
"extra_label": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"client_group_ids": {
"type": "array",
"items": {
"type": "integer"
}
}
}
}
Response 200 OK
{
"client": {
"id": 0,
"uuid": "string",
"label": "string",
"extra_label": "string",
"tags": [
"string"
],
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z",
"disabled_at": "2026-01-15T10:30:00Z",
"disabled_reason": "string",
"registration_key": {
"id": 0,
"registration_key": "string",
"comment": "string",
"valid_from": "2026-01-15T10:30:00Z",
"valid_until": "2026-01-15T10:30:00Z",
"num_registrations_left": 0,
"usage_limit_days": 0
},
"client_groups": [
{
"id": 0,
"name": "string"
}
]
}
}
Schema of the response body
{
"description": "Response for client disable action",
"type": "object",
"required": [
"client"
],
"properties": {
"client": {
"type": "object",
"required": [
"id",
"uuid",
"created_at",
"updated_at",
"client_groups"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"label": {
"type": "string",
"nullable": true
},
"extra_label": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"disabled_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"disabled_reason": {
"type": "string",
"nullable": true
},
"registration_key": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"registration_key": {
"type": "string"
},
"comment": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"valid_until": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"num_registrations_left": {
"type": "integer",
"nullable": true
},
"usage_limit_days": {
"type": "integer",
"nullable": true
}
},
"nullable": true
},
"client_groups": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
}
Schemas¶
ClientCheckLabelAvailabilityResponse¶
| Name | Type |
|---|---|
available |
boolean |
label |
string |
ClientDisableResponse¶
| Name | Type |
|---|---|
client |
Properties: id, uuid, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, registration_key, client_groups |
ClientIndexResponse¶
| Name | Type |
|---|---|
clients |
Array<Properties: id, uuid, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, last_measurement_at, registration_key, client_groups, current_isp_contract> |
ClientShowResponse¶
| Name | Type |
|---|---|
client |
Properties: id, uuid, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, last_measurement_at, registration_key, client_groups, current_isp_contract |
ClientUpdateData¶
| Name | Type |
|---|---|
client_group_ids |
Array<integer> |
extra_label |
string| null |
label |
string| null |
tags |
Array<string> |
ClientUpdateResponse¶
| Name | Type |
|---|---|
client |
Properties: id, uuid, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, last_measurement_at, registration_key, client_groups |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| ApiKeyAuth | apiKey | API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys. |