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",
"access_level": "owner",
"type": "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",
"last_client_type": "string",
"last_client_version": "string",
"last_seen_at": "2026-01-15T10:30:00Z",
"config_managed": true,
"delivered_public_config": {
"id": 0,
"name": "string",
"is_default": true
},
"delivered_automator_config": {
"id": 0,
"name": "string",
"is_default": true
},
"offline": true,
"anomalies_muted": true,
"offline_notifications_muted": true,
"system_health_notifications_muted": true,
"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",
"type",
"created_at",
"updated_at",
"client_groups",
"access_level"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"access_level": {
"type": "string",
"enum": [
"owner",
"shared"
]
},
"type": {
"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"
},
"last_client_type": {
"type": "string",
"nullable": true
},
"last_client_version": {
"type": "string",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"config_managed": {
"description": "Whether the server delivers configs to the client. Null for shared clients.",
"type": "boolean",
"nullable": true
},
"delivered_public_config": {
"description": "The measurement config the client receives: the assigned one, or else the default. Null for shared clients or when there is none.",
"type": "object",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"delivered_automator_config": {
"description": "The schedule config the client receives: the assigned one, or else the default. Null for shared clients or when there is none.",
"type": "object",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"offline": {
"type": "boolean",
"nullable": true
},
"anomalies_muted": {
"type": "boolean"
},
"offline_notifications_muted": {
"type": "boolean"
},
"system_health_notifications_muted": {
"type": "boolean"
},
"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",
"access_level": "owner",
"type": "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",
"last_client_type": "string",
"last_client_version": "string",
"last_seen_at": "2026-01-15T10:30:00Z",
"config_managed": true,
"delivered_public_config": {
"id": 0,
"name": "string",
"is_default": true
},
"delivered_automator_config": {
"id": 0,
"name": "string",
"is_default": true
},
"configuration": {
"managed": true,
"public_config": {
"assignment": {
"id": 0,
"config_id": 0,
"config_name": "string",
"source": "manual",
"source_client_group_id": 0,
"source_client_group_name": "string",
"assigned_by_id": 0,
"assigned_by_name": "string",
"valid_from": "2026-01-15T10:30:00Z"
},
"delivered": {
"id": 0,
"name": "string",
"is_default": true,
"published_revision": 0
}
},
"automator_config": {
"assignment": {
"id": 0,
"config_id": 0,
"config_name": "string",
"source": "manual",
"source_client_group_id": 0,
"source_client_group_name": "string",
"assigned_by_id": 0,
"assigned_by_name": "string",
"valid_from": "2026-01-15T10:30:00Z"
},
"delivered": {
"id": 0,
"name": "string",
"is_default": true,
"published_revision": 0
}
},
"local_public_config": {},
"local_automator_config": {},
"effective_service_credentials": [
{
"service": "string",
"id": 0,
"name": "string",
"username": "string",
"source": "client"
}
],
"service_credentials": [
{
"id": 0,
"name": "string",
"service": "string",
"username": "string",
"password_set": true,
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
],
"last_config_check_at": "2026-01-15T10:30:00Z",
"last_config_download_at": "2026-01-15T10:30:00Z",
"last_pulled_config_hash": "string",
"last_pulled_public_config": {
"id": 0,
"name": "string",
"is_default": true
},
"last_pulled_public_config_revision": 0,
"last_pulled_automator_config": {
"id": 0,
"name": "string",
"is_default": true
},
"last_pulled_automator_config_revision": 0,
"missing_study_ids": [
"string"
],
"next_scheduled_runs": {
"timezone": "string",
"timezone_source": "config",
"entries": [
{
"id": "string",
"kind": "study",
"study_id": null,
"schedule": "string",
"interval": "string",
"runs": [
"2026-01-15T10:30:00Z"
]
}
]
}
},
"offline": true,
"anomalies_muted": true,
"offline_notifications_muted": true,
"system_health_notifications_muted": true,
"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",
"type",
"created_at",
"updated_at",
"client_groups",
"access_level"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"access_level": {
"type": "string",
"enum": [
"owner",
"shared"
]
},
"type": {
"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"
},
"last_client_type": {
"type": "string",
"nullable": true
},
"last_client_version": {
"type": "string",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"config_managed": {
"description": "Whether the server delivers configs to the client. Null for shared clients.",
"type": "boolean",
"nullable": true
},
"delivered_public_config": {
"description": "The measurement config the client receives: the assigned one, or else the default. Null for shared clients or when there is none.",
"type": "object",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"delivered_automator_config": {
"description": "The schedule config the client receives: the assigned one, or else the default. Null for shared clients or when there is none.",
"type": "object",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"configuration": {
"type": "object",
"description": "Configuration of the client. Only for the owning data owner, and only on show and update.",
"required": [
"managed",
"public_config",
"automator_config",
"local_public_config",
"local_automator_config",
"service_credentials",
"effective_service_credentials",
"next_scheduled_runs",
"missing_study_ids"
],
"properties": {
"managed": {
"type": "boolean"
},
"public_config": {
"type": "object",
"required": [
"assignment",
"delivered"
],
"properties": {
"assignment": {
"type": "object",
"description": "The active assignment, or null when the client gets the default config",
"required": [
"id",
"config_id",
"config_name",
"source",
"valid_from"
],
"properties": {
"id": {
"type": "integer"
},
"config_id": {
"type": "integer"
},
"config_name": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"manual",
"group",
"template",
"schedule_config"
]
},
"source_client_group_id": {
"type": "integer",
"nullable": true
},
"source_client_group_name": {
"type": "string",
"nullable": true
},
"assigned_by_id": {
"type": "integer",
"nullable": true
},
"assigned_by_name": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
}
},
"nullable": true
},
"delivered": {
"type": "object",
"description": "The config the client receives: the assigned one, or else the default",
"required": [
"id",
"name",
"is_default",
"published_revision"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"published_revision": {
"type": "integer",
"nullable": true
}
},
"nullable": true
}
}
},
"automator_config": {
"type": "object",
"required": [
"assignment",
"delivered"
],
"properties": {
"assignment": {
"type": "object",
"description": "The active assignment, or null when the client gets the default config",
"required": [
"id",
"config_id",
"config_name",
"source",
"valid_from"
],
"properties": {
"id": {
"type": "integer"
},
"config_id": {
"type": "integer"
},
"config_name": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"manual",
"group",
"template",
"schedule_config"
]
},
"source_client_group_id": {
"type": "integer",
"nullable": true
},
"source_client_group_name": {
"type": "string",
"nullable": true
},
"assigned_by_id": {
"type": "integer",
"nullable": true
},
"assigned_by_name": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
}
},
"nullable": true
},
"delivered": {
"type": "object",
"description": "The config the client receives: the assigned one, or else the default",
"required": [
"id",
"name",
"is_default",
"published_revision"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"published_revision": {
"type": "integer",
"nullable": true
}
},
"nullable": true
}
}
},
"local_public_config": {
"type": "object",
"description": "Overrides deep-merged over the composed publicConfig.json"
},
"local_automator_config": {
"type": "object",
"description": "Overrides deep-merged over the composed automatorConfig.json"
},
"effective_service_credentials": {
"type": "array",
"description": "The login of each service that goes into publicConfig.json",
"items": {
"type": "object",
"required": [
"service",
"id",
"name",
"username",
"source"
],
"properties": {
"service": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string",
"nullable": true
},
"source": {
"type": "string",
"enum": [
"client",
"organization"
]
}
},
"additionalProperties": false
}
},
"service_credentials": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"service",
"password_set"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"service": {
"type": "string"
},
"username": {
"type": "string",
"nullable": true
},
"password_set": {
"type": "boolean"
},
"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"
}
}
}
},
"last_config_check_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"last_config_download_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"last_pulled_config_hash": {
"type": "string",
"nullable": true
},
"last_pulled_public_config": {
"type": "object",
"description": "The measurement config of the last download. Null before the first download, and when the config was deleted.",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"last_pulled_public_config_revision": {
"type": "integer",
"nullable": true
},
"last_pulled_automator_config": {
"type": "object",
"description": "The schedule config of the last download. Null before the first download, and when the config was deleted.",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"last_pulled_automator_config_revision": {
"type": "integer",
"nullable": true
},
"missing_study_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Studies the delivered schedule config names that the delivered measurement config lacks."
},
"next_scheduled_runs": {
"type": "object",
"description": "Next run times of the cron entries of the delivered schedule config, followed by its update checks.",
"required": [
"timezone",
"timezone_source",
"entries"
],
"properties": {
"timezone": {
"type": "string",
"description": "IANA time zone the run times were computed in"
},
"timezone_source": {
"type": "string",
"enum": [
"config",
"assumed"
],
"description": "config: the config sets globalScheduleSettings.timeZone and the probe fires in that zone. assumed: the probe fires in its own time zone, which the server does not know, and the times assume UTC."
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"kind",
"runs"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"study",
"config_update",
"software_update"
],
"description": "study: an entry of studySchedules. config_update and software_update: the update checks of the updates section. Without updates.config.schedule, the config is pulled every 15 minutes."
},
"study_id": {
"description": "Only for studies",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"schedule": {
"type": "string"
},
"interval": {
"type": "string"
},
"runs": {
"type": "array",
"items": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"description": "Empty for interval entries"
}
}
}
}
},
"nullable": true
}
}
},
"offline": {
"type": "boolean",
"nullable": true
},
"anomalies_muted": {
"type": "boolean"
},
"offline_notifications_muted": {
"type": "boolean"
},
"system_health_notifications_muted": {
"type": "boolean"
},
"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
Response 200 OK
{
"client": {
"id": 0,
"uuid": "string",
"access_level": "owner",
"type": "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",
"last_client_type": "string",
"last_client_version": "string",
"last_seen_at": "2026-01-15T10:30:00Z",
"config_managed": true,
"delivered_public_config": {
"id": 0,
"name": "string",
"is_default": true
},
"delivered_automator_config": {
"id": 0,
"name": "string",
"is_default": true
},
"configuration": {
"managed": true,
"public_config": {
"assignment": {
"id": 0,
"config_id": 0,
"config_name": "string",
"source": "manual",
"source_client_group_id": 0,
"source_client_group_name": "string",
"assigned_by_id": 0,
"assigned_by_name": "string",
"valid_from": "2026-01-15T10:30:00Z"
},
"delivered": {
"id": 0,
"name": "string",
"is_default": true,
"published_revision": 0
}
},
"automator_config": {
"assignment": {
"id": 0,
"config_id": 0,
"config_name": "string",
"source": "manual",
"source_client_group_id": 0,
"source_client_group_name": "string",
"assigned_by_id": 0,
"assigned_by_name": "string",
"valid_from": "2026-01-15T10:30:00Z"
},
"delivered": {
"id": 0,
"name": "string",
"is_default": true,
"published_revision": 0
}
},
"local_public_config": {},
"local_automator_config": {},
"effective_service_credentials": [
{
"service": "string",
"id": 0,
"name": "string",
"username": "string",
"source": "client"
}
],
"service_credentials": [
{
"id": 0,
"name": "string",
"service": "string",
"username": "string",
"password_set": true,
"created_at": "2026-01-15T10:30:00Z",
"updated_at": "2026-01-15T10:30:00Z"
}
],
"last_config_check_at": "2026-01-15T10:30:00Z",
"last_config_download_at": "2026-01-15T10:30:00Z",
"last_pulled_config_hash": "string",
"last_pulled_public_config": {
"id": 0,
"name": "string",
"is_default": true
},
"last_pulled_public_config_revision": 0,
"last_pulled_automator_config": {
"id": 0,
"name": "string",
"is_default": true
},
"last_pulled_automator_config_revision": 0,
"missing_study_ids": [
"string"
],
"next_scheduled_runs": {
"timezone": "string",
"timezone_source": "config",
"entries": [
{
"id": "string",
"kind": "study",
"study_id": null,
"schedule": "string",
"interval": "string",
"runs": [
"2026-01-15T10:30:00Z"
]
}
]
}
},
"offline": true,
"anomalies_muted": true,
"offline_notifications_muted": true,
"system_health_notifications_muted": true,
"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",
"type",
"created_at",
"updated_at",
"client_groups",
"access_level"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"access_level": {
"type": "string",
"enum": [
"owner",
"shared"
]
},
"type": {
"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"
},
"last_client_type": {
"type": "string",
"nullable": true
},
"last_client_version": {
"type": "string",
"nullable": true
},
"last_seen_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"config_managed": {
"description": "Whether the server delivers configs to the client. Null for shared clients.",
"type": "boolean",
"nullable": true
},
"delivered_public_config": {
"description": "The measurement config the client receives: the assigned one, or else the default. Null for shared clients or when there is none.",
"type": "object",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"delivered_automator_config": {
"description": "The schedule config the client receives: the assigned one, or else the default. Null for shared clients or when there is none.",
"type": "object",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"configuration": {
"type": "object",
"description": "Configuration of the client. Only for the owning data owner, and only on show and update.",
"required": [
"managed",
"public_config",
"automator_config",
"local_public_config",
"local_automator_config",
"service_credentials",
"effective_service_credentials",
"next_scheduled_runs",
"missing_study_ids"
],
"properties": {
"managed": {
"type": "boolean"
},
"public_config": {
"type": "object",
"required": [
"assignment",
"delivered"
],
"properties": {
"assignment": {
"type": "object",
"description": "The active assignment, or null when the client gets the default config",
"required": [
"id",
"config_id",
"config_name",
"source",
"valid_from"
],
"properties": {
"id": {
"type": "integer"
},
"config_id": {
"type": "integer"
},
"config_name": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"manual",
"group",
"template",
"schedule_config"
]
},
"source_client_group_id": {
"type": "integer",
"nullable": true
},
"source_client_group_name": {
"type": "string",
"nullable": true
},
"assigned_by_id": {
"type": "integer",
"nullable": true
},
"assigned_by_name": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
}
},
"nullable": true
},
"delivered": {
"type": "object",
"description": "The config the client receives: the assigned one, or else the default",
"required": [
"id",
"name",
"is_default",
"published_revision"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"published_revision": {
"type": "integer",
"nullable": true
}
},
"nullable": true
}
}
},
"automator_config": {
"type": "object",
"required": [
"assignment",
"delivered"
],
"properties": {
"assignment": {
"type": "object",
"description": "The active assignment, or null when the client gets the default config",
"required": [
"id",
"config_id",
"config_name",
"source",
"valid_from"
],
"properties": {
"id": {
"type": "integer"
},
"config_id": {
"type": "integer"
},
"config_name": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"manual",
"group",
"template",
"schedule_config"
]
},
"source_client_group_id": {
"type": "integer",
"nullable": true
},
"source_client_group_name": {
"type": "string",
"nullable": true
},
"assigned_by_id": {
"type": "integer",
"nullable": true
},
"assigned_by_name": {
"type": "string",
"nullable": true
},
"valid_from": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
}
},
"nullable": true
},
"delivered": {
"type": "object",
"description": "The config the client receives: the assigned one, or else the default",
"required": [
"id",
"name",
"is_default",
"published_revision"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"published_revision": {
"type": "integer",
"nullable": true
}
},
"nullable": true
}
}
},
"local_public_config": {
"type": "object",
"description": "Overrides deep-merged over the composed publicConfig.json"
},
"local_automator_config": {
"type": "object",
"description": "Overrides deep-merged over the composed automatorConfig.json"
},
"effective_service_credentials": {
"type": "array",
"description": "The login of each service that goes into publicConfig.json",
"items": {
"type": "object",
"required": [
"service",
"id",
"name",
"username",
"source"
],
"properties": {
"service": {
"type": "string"
},
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"username": {
"type": "string",
"nullable": true
},
"source": {
"type": "string",
"enum": [
"client",
"organization"
]
}
},
"additionalProperties": false
}
},
"service_credentials": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"service",
"password_set"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"service": {
"type": "string"
},
"username": {
"type": "string",
"nullable": true
},
"password_set": {
"type": "boolean"
},
"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"
}
}
}
},
"last_config_check_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"last_config_download_at": {
"type": "string",
"format": "date-time",
"nullable": true,
"example": "2026-01-15T10:30:00Z"
},
"last_pulled_config_hash": {
"type": "string",
"nullable": true
},
"last_pulled_public_config": {
"type": "object",
"description": "The measurement config of the last download. Null before the first download, and when the config was deleted.",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"last_pulled_public_config_revision": {
"type": "integer",
"nullable": true
},
"last_pulled_automator_config": {
"type": "object",
"description": "The schedule config of the last download. Null before the first download, and when the config was deleted.",
"required": [
"id",
"name",
"is_default"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
}
},
"nullable": true
},
"last_pulled_automator_config_revision": {
"type": "integer",
"nullable": true
},
"missing_study_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Studies the delivered schedule config names that the delivered measurement config lacks."
},
"next_scheduled_runs": {
"type": "object",
"description": "Next run times of the cron entries of the delivered schedule config, followed by its update checks.",
"required": [
"timezone",
"timezone_source",
"entries"
],
"properties": {
"timezone": {
"type": "string",
"description": "IANA time zone the run times were computed in"
},
"timezone_source": {
"type": "string",
"enum": [
"config",
"assumed"
],
"description": "config: the config sets globalScheduleSettings.timeZone and the probe fires in that zone. assumed: the probe fires in its own time zone, which the server does not know, and the times assume UTC."
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"kind",
"runs"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string",
"enum": [
"study",
"config_update",
"software_update"
],
"description": "study: an entry of studySchedules. config_update and software_update: the update checks of the updates section. Without updates.config.schedule, the config is pulled every 15 minutes."
},
"study_id": {
"description": "Only for studies",
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"schedule": {
"type": "string"
},
"interval": {
"type": "string"
},
"runs": {
"type": "array",
"items": {
"type": "string",
"format": "date-time",
"example": "2026-01-15T10:30:00Z"
},
"description": "Empty for interval entries"
}
}
}
}
},
"nullable": true
}
}
},
"offline": {
"type": "boolean",
"nullable": true
},
"anomalies_muted": {
"type": "boolean"
},
"offline_notifications_muted": {
"type": "boolean"
},
"system_health_notifications_muted": {
"type": "boolean"
},
"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"
}
}
}
}
}
}
}
}
PATCH /clients/{id}/notification_preferences¶
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
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 |
Response 200 OK
{
"client": {
"id": 0,
"uuid": "string",
"access_level": "owner",
"type": "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",
"anomalies_muted": true,
"offline_notifications_muted": true,
"system_health_notifications_muted": true,
"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",
"type",
"created_at",
"updated_at",
"client_groups",
"access_level"
],
"properties": {
"id": {
"type": "integer"
},
"uuid": {
"type": "string"
},
"access_level": {
"type": "string",
"enum": [
"owner",
"shared"
]
},
"type": {
"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
},
"anomalies_muted": {
"type": "boolean"
},
"offline_notifications_muted": {
"type": "boolean"
},
"system_health_notifications_muted": {
"type": "boolean"
},
"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}/mute¶
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
POST /clients/{id}/unmute¶
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
Schemas¶
ClientCheckLabelAvailabilityResponse¶
| Name | Type |
|---|---|
available |
boolean |
label |
string |
ClientDisableResponse¶
| Name | Type |
|---|---|
client |
Properties: id, uuid, access_level, type, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, anomalies_muted, offline_notifications_muted, system_health_notifications_muted, registration_key, client_groups |
ClientIndexResponse¶
| Name | Type |
|---|---|
clients |
Array<Properties: id, uuid, access_level, type, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, last_measurement_at, last_client_type, last_client_version, last_seen_at, config_managed, delivered_public_config, delivered_automator_config, offline, anomalies_muted, offline_notifications_muted, system_health_notifications_muted, registration_key, client_groups, current_isp_contract> |
ClientNotificationPreferencesUpdateData¶
| Name | Type |
|---|---|
anomalies_muted |
boolean |
offline_notifications_muted |
boolean |
system_health_notifications_muted |
boolean |
ClientShowResponse¶
| Name | Type |
|---|---|
client |
Properties: id, uuid, access_level, type, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, last_measurement_at, last_client_type, last_client_version, last_seen_at, config_managed, delivered_public_config, delivered_automator_config, configuration, offline, anomalies_muted, offline_notifications_muted, system_health_notifications_muted, registration_key, client_groups, current_isp_contract |
ClientUpdateResponse¶
| Name | Type |
|---|---|
client |
Properties: id, uuid, access_level, type, label, extra_label, tags, created_at, updated_at, disabled_at, disabled_reason, last_measurement_at, last_client_type, last_client_version, last_seen_at, config_managed, delivered_public_config, delivered_automator_config, configuration, offline, anomalies_muted, offline_notifications_muted, system_health_notifications_muted, 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. |