POST Approve the device and its separate CLI/MCP management credential
/api/v1/agent/device-link
Requires CSRF. Select an owned workspace or create one; choose an unconfigured server or create one. Defaults select CPU, RAM and the system filesystem at 30 seconds. Account quotas are enforced in the same transaction. Replays by the same account do not create more keys; another account cannot approve an already completed request.
On this page
Access and permissions
Requires CSRF. Select an owned workspace or create one; choose an unconfigured server or create one. Defaults select CPU, RAM and the system filesystem at 30 seconds. Account quotas are enforced in the same transaction. Replays by the same account do not create more keys; another account cannot approve an already completed request.
Browser session: __Host-mb_session cookie.
Parameters and headers
No path, query or additional request-header parameters.
Request body
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | DeviceLinkApproval | Yes | — |
| $.code | string; {"pattern":"^[0-9]{8}$"} | Yes | — |
| $.device_id | string; {"format":"uuid"} | No | — |
| $.name | string; {"maxLength":128,"minLength":1} | Yes | — |
| $.selections | array<AgentSelection>; {"maxItems":200} | No | — |
| $.selections[] | AgentSelection | Yes | — |
| $.selections[].component_id | string | Yes | — |
| $.selections[].interval_seconds | integer; {"maximum":86400,"minimum":1} | Yes | — |
| $.selections[].parameter_key | string | Yes | — |
| $.workspace_id | string; {"format":"uuid"} | No | — |
| $.workspace_name | string; {"maxLength":128,"minLength":1} | No | — |
| $.server_profile | ServerProfileRequest | No | — |
| $.server_profile.components | array<object>; {"maxItems":200} | null | No | Discovered or explicitly selected server components. |
| $.server_profile.components (anyOf 1) | array<object>; {"maxItems":200} | No | — |
| $.server_profile.components (anyOf 1)[] | object | Yes | — |
| $.server_profile.components (anyOf 1)[].address | string | No | — |
| $.server_profile.components (anyOf 1)[].family | string | No | — |
| $.server_profile.components (anyOf 1)[].id | string | Yes | UUID of this resource. Keep the returned identifier for subsequent operations. |
| $.server_profile.components (anyOf 1)[].kind | string | Yes | Resource kind or measurement type selected from the listed values. |
| $.server_profile.components (anyOf 1)[].label | string; {"maxLength":128,"minLength":1} | Yes | Display name for the component. |
| $.server_profile.components (anyOf 1)[].local_ref | string | No | — |
| $.server_profile.components (anyOf 1)[].name | string | No | Human-readable resource name. Follow the listed length limit. |
| $.server_profile.components (anyOf 1)[].path | string; {"maxLength":1024} | No | — |
| $.server_profile.components (anyOf 1)[].port | integer | No | — |
| $.server_profile.components (anyOf 1)[].project | string | No | — |
| $.server_profile.components (anyOf 1)[].protocol | string | No | — |
| $.server_profile.components (anyOf 1)[].text_languages | object | No | — |
| $.server_profile.components (anyOf 1)[].timeout_seconds | integer | No | — |
| $.server_profile.components (anyOf 1)[].translations | object; {"additionalProperties":false} | No | — |
| $.server_profile.components (anyOf 1)[].translations.de | object | No | — |
| $.server_profile.components (anyOf 1)[].translations.en | object | No | — |
| $.server_profile.components (anyOf 1)[].transport | string | No | — |
| $.server_profile.components (anyOf 1)[].filesystem_identity | string; {"maxLength":256} | No | Agent-reported volume identity. Keep it unchanged to prevent a replacement volume from continuing another volume’s history. |
| $.server_profile.components (anyOf 1)[].disk_identity | string; {"maxLength":256} | No | — |
| $.server_profile.components (anyOf 2) | null | No | — |
| $.server_profile.selections | array<object>; {"maxItems":200} | null | No | Selected component/parameter pairs and sampling intervals. |
| $.server_profile.selections (anyOf 1) | array<object>; {"maxItems":200} | No | — |
| $.server_profile.selections (anyOf 1)[] | object | Yes | — |
| $.server_profile.selections (anyOf 1)[].component_id | string | Yes | Stable identifier of the selected or discovered component. |
| $.server_profile.selections (anyOf 1)[].interval_seconds | integer; {"maximum":86400,"minimum":0} | No | Sampling or check interval in seconds within the stated bounds. |
| $.server_profile.selections (anyOf 1)[].parameter_key | string | Yes | Stable parameter identifier from the server catalog. |
| $.server_profile.selections (anyOf 2) | null | No | — |
| $.server_profile.version | JSON; {"const":2} | Yes | — |
| $.server_profile.overview | object; {"additionalProperties":false} | No | Explicit targets for the six-chart server overview; select all required readings. |
| $.server_profile.overview.system_id | string; {"maxLength":128} | Yes | — |
| $.server_profile.overview.filesystem_id | string; {"maxLength":128} | Yes | — |
| $.server_profile.overview.disk_id | string; {"maxLength":128} | Yes | — |
| $.server_profile.overview.network_id | string; {"maxLength":128} | Yes | — |
| $.server_profile.filesystem_discovery | object; {"additionalProperties":false} | No | Optional local filesystem discovery with a base interval of at least 10 seconds. New Server/NAS setups enable it. Existing profiles require explicit activation. Manually disabled measurements are preserved. |
| $.server_profile.filesystem_discovery.mode | string; {"enum":["off","local"]} | Yes | — |
| $.server_profile.filesystem_discovery.interval_seconds | integer; {"minimum":10,"maximum":86400} | Yes | — |
| $.server_profile.system_discovery | object; {"additionalProperties":false} | No | — |
| $.server_profile.system_discovery.mode | string; {"enum":["off","local"]} | Yes | — |
| $.server_profile.system_discovery.interval_seconds | integer; {"minimum":10,"maximum":86400} | Yes | — |
| $.server_profile.global_interval_seconds | integer; {"minimum":1,"maximum":86400} | No | Explicit global sampling choice. Each source still applies its platform minimum; individual fast rows never imply this choice. |
Responses
application/json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | object; {"additionalProperties":false} | Yes | — |
| $.approved | boolean | Yes | — |
| $.replayed | boolean | Yes | — |
| Stable error codes |
|---|
| invalid_link |
| not_found |
| Stable error codes |
|---|
| revision_conflict |
| Stable error codes |
|---|
| invalid_link |
| invalid_profile |
| unsupported_parameter |
| Stable error codes |
|---|
| creation_quota |
| Stable error codes |
|---|
| unavailable |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
Retries and asynchronous work
This change does not have a general retry guarantee. If the response is unclear, read the affected resource before trying again. Follow Retry-After waiting times and request new sign-in or action codes when they expire.
Request examples
Replace demo IDs, timestamps and placeholders with your own values. For a retry, keep the same IDs, time and content. These examples do not run requests on this page.
Keep login links, codes, cookies and keys private. Do not print them in logs or share them in support requests.
curl --fail-with-body --request POST https://metribeacon.com/api/v1/agent/device-link --header 'Accept: application/json' --header 'Cookie: __Host-mb_session=YOUR_SESSION; __Host-mb_csrf=YOUR_CSRF' --header 'Content-Type: application/json' --header 'Origin: https://metribeacon.com' --header 'X-CSRF-Token: YOUR_CSRF' --data '{"code":"12345678","name":"Demo device"}'import urllib.request
headers = {'Accept': 'application/json', 'Cookie': '__Host-mb_session=YOUR_SESSION; __Host-mb_csrf=YOUR_CSRF', 'Content-Type': 'application/json', 'Origin': 'https://metribeacon.com', 'X-CSRF-Token': 'YOUR_CSRF'}
request = urllib.request.Request('https://metribeacon.com/api/v1/agent/device-link', headers=headers, method='POST', data='{"code":"12345678","name":"Demo device"}'.encode())
with urllib.request.urlopen(request) as response:
print(response.read().decode())
const response = await fetch("https://metribeacon.com/api/v1/agent/device-link", {"method": "POST", "headers": {"Accept": "application/json", "Cookie": "__Host-mb_session=YOUR_SESSION; __Host-mb_csrf=YOUR_CSRF", "Content-Type": "application/json", "Origin": "https://metribeacon.com", "X-CSRF-Token": "YOUR_CSRF"}, "body": "{\"code\":\"12345678\",\"name\":\"Demo device\"}"});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
package main
import ("fmt"; "io"; "net/http"; "strings")
func main() {
req, err := http.NewRequest("POST", "https://metribeacon.com/api/v1/agent/device-link", strings.NewReader("{\"code\":\"12345678\",\"name\":\"Demo device\"}")); if err != nil { panic(err) }
req.Header.Set("Accept", "application/json")
req.Header.Set("Cookie", "__Host-mb_session=YOUR_SESSION; __Host-mb_csrf=YOUR_CSRF")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Origin", "https://metribeacon.com")
req.Header.Set("X-CSRF-Token", "YOUR_CSRF")
response, err := http.DefaultClient.Do(req); if err != nil { panic(err) }; defer response.Body.Close(); data, err := io.ReadAll(response.Body); if err != nil { panic(err) }; fmt.Printf("HTTP %d\n%s\n", response.StatusCode, data)
}
Related guides
- HTTP API, OAuth and MCP
Find the user API endpoints, their permissions, fields, examples and response formats.
- GET Inspect a short confirmation code as a signed-in user
Inspect a short confirmation code as a signed-in user
- POST Reject a pending device link
Reject a pending device link
- GET Confirm that heartbeat and an enabled measurement were accepted
Confirm the selected agent profile through saved data: a heartbeat and a numeric or state value from an enabled profile series, received since the requested time. Installer and process status do not establish readiness.