POST Enroll a server with an installation code
/api/v1/agent/install-codes/redeem
Atomically creates or connects the bound server, profile, groups and a device-scoped key from the locally generated key hash. Identical claims resume safely; a private device key can recover a committed claim after code expiry.
On this page
Access and permissions
Atomically creates or connects the bound server, profile, groups and a device-scoped key from the locally generated key hash. Identical claims resume safely; a private device key can recover a committed claim after code expiry.
agentInstallCode
Parameters and headers
No path, query or additional request-header parameters.
Request body
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | AgentInstallClaim | Yes | — |
| $.installation_id | string | Yes | Installation setting or machine-reported value. |
| $.name | string | Yes | Installation setting or machine-reported value. |
| $.platform | string | Yes | Installation setting or machine-reported value. |
| $.architecture | string | Yes | Installation setting or machine-reported value. |
| $.system_drive | string | Yes | Installation setting or machine-reported value. |
| $.key_prefix | string | Yes | Installation setting or machine-reported value. |
| $.key_hash | string | Yes | Installation setting or machine-reported value. |
| $.version | string | Yes | Installation setting or machine-reported value. |
| $.expected_account_id | string | No | Installation setting or machine-reported value. |
| $.setup_targets | array<object>; {"minItems":2,"maxItems":200} | No | Automatically detected system, local data filesystems, root disk and network interface routed to the backend. Boot, temporary, container and network filesystems are excluded. Custom profiles remain unchanged. |
| $.setup_targets[] | object | Yes | — |
| $.setup_targets[].address | string | No | — |
| $.setup_targets[].family | string | No | — |
| $.setup_targets[].id | string | Yes | UUID of this resource. Keep the returned identifier for subsequent operations. |
| $.setup_targets[].kind | string | Yes | Resource kind or measurement type selected from the listed values. |
| $.setup_targets[].label | string; {"maxLength":128,"minLength":1} | Yes | Display name for the component. |
| $.setup_targets[].local_ref | string | No | — |
| $.setup_targets[].name | string | No | Human-readable resource name. Follow the listed length limit. |
| $.setup_targets[].path | string; {"maxLength":1024} | No | — |
| $.setup_targets[].port | integer | No | — |
| $.setup_targets[].project | string | No | — |
| $.setup_targets[].protocol | string | No | — |
| $.setup_targets[].text_languages | object | No | — |
| $.setup_targets[].timeout_seconds | integer | No | — |
| $.setup_targets[].translations | object; {"additionalProperties":false} | No | — |
| $.setup_targets[].translations.de | object | No | — |
| $.setup_targets[].translations.en | object | No | — |
| $.setup_targets[].transport | string | No | — |
| $.setup_targets[].filesystem_identity | string; {"maxLength":256} | No | Agent-reported volume identity. Keep it unchanged to prevent a replacement volume from continuing another volume’s history. |
| $.setup_targets[].disk_identity | string; {"maxLength":256} | No | — |
| $.system_inventory | object; {"additionalProperties":false} | No | — |
| $.system_inventory.version | integer; {"enum":[1]} | Yes | — |
| $.system_inventory.disks_known | boolean | Yes | — |
| $.system_inventory.disks | array<object; {"additionalProperties":false}>; {"maxItems":200} | Yes | — |
| $.system_inventory.disks[] | object; {"additionalProperties":false} | Yes | — |
| $.system_inventory.disks[].component_id | string; {"maxLength":192} | Yes | — |
| $.system_inventory.disks[].path | string; {"maxLength":1024} | Yes | — |
| $.system_inventory.disks[].label | string; {"maxLength":128} | Yes | — |
| $.system_inventory.disks[].identity | string; {"maxLength":256} | Yes | — |
| $.system_inventory.swap_active | boolean | null | Yes | — |
| $.system_inventory.process_count_available | boolean | Yes | — |
| $.system_inventory.disk_io | LogicalDiskIOInventory | null | No | — |
| $.system_inventory.disk_io (anyOf 1) | LogicalDiskIOInventory | No | — |
| $.system_inventory.disk_io (anyOf 1).complete | boolean | Yes | — |
| $.system_inventory.disk_io (anyOf 1).disk_count_known | boolean | Yes | — |
| $.system_inventory.disk_io (anyOf 1).disk_count | integer; {"minimum":0,"maximum":200} | Yes | — |
| $.system_inventory.disk_io (anyOf 1).source_count | integer; {"minimum":0,"maximum":1024} | Yes | — |
| $.system_inventory.disk_io (anyOf 1).source_set | string; {"maxLength":64} | Yes | — |
| $.system_inventory.disk_io (anyOf 2) | null | No | — |
| $.system_inventory.health | ServerHealthInventory | null | No | — |
| $.system_inventory.health (anyOf 1) | ServerHealthInventory | No | — |
| $.system_inventory.health (anyOf 1).version | integer; {"const":1} | Yes | — |
| $.system_inventory.health (anyOf 1).sources | array<ServerHealthSource>; {"maxItems":1200} | Yes | — |
| $.system_inventory.health (anyOf 1).sources[] | ServerHealthSource | Yes | — |
| $.system_inventory.health (anyOf 1).sources[].component | ServerComponent | Yes | — |
| $.system_inventory.health (anyOf 1).sources[].component.address | string | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.family | string | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.id | string | Yes | UUID of this resource. Keep the returned identifier for subsequent operations. |
| $.system_inventory.health (anyOf 1).sources[].component.kind | string | Yes | Resource kind or measurement type selected from the listed values. |
| $.system_inventory.health (anyOf 1).sources[].component.label | string | Yes | Display name for the component. |
| $.system_inventory.health (anyOf 1).sources[].component.local_ref | string | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.name | string | No | Human-readable resource name. Follow the listed length limit. |
| $.system_inventory.health (anyOf 1).sources[].component.path | string | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.port | integer | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.project | string | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.protocol | string | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.text_languages | object | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.timeout_seconds | integer | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.translations | object; {"additionalProperties":false} | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.translations.de | object | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.translations.en | object | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.transport | string | No | — |
| $.system_inventory.health (anyOf 1).sources[].component.filesystem_identity | string; {"maxLength":256} | No | Agent-reported volume identity. Keep it unchanged to prevent a replacement volume from continuing another volume’s history. |
| $.system_inventory.health (anyOf 1).sources[].component.disk_identity | string; {"maxLength":256} | No | — |
| $.system_inventory.health (anyOf 1).sources[].group | string; {"enum":["cpu_diagnostics_v1","disk_operations_v1","disk_latency_v1","network_errors_v1","swap_traffic_v1","psi_v1","filesystem_capacity_v1","filesystem_inodes_v1","filesystem_health_v1","oom_v1","storage_health_v1"]} | Yes | — |
| $.system_inventory.health (anyOf 1).sources[].status | string; {"enum":["ready","unsupported","permission_denied","failed"]} | Yes | — |
| $.system_inventory.health (anyOf 1).sources[].minimum_interval_seconds | integer; {"minimum":1,"maximum":86400} | Yes | — |
| $.system_inventory.health (anyOf 2) | null | No | — |
Responses
application/json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | AgentInstallReceipt | Yes | — |
| $.account_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.workspace_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.device_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.key_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.replayed | boolean | Yes | Installation setting or machine-reported value. |
application/json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | AgentInstallReceipt | Yes | — |
| $.account_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.workspace_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.device_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.key_id | string; {"format":"uuid"} | Yes | Installation setting or machine-reported value. |
| $.replayed | boolean | Yes | Installation setting or machine-reported value. |
| Stable error codes |
|---|
| invalid_install |
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 | — |
| Stable error codes |
|---|
| forbidden |
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 | — |
| Stable error codes |
|---|
| not_found |
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 | — |
| Stable error codes |
|---|
| install_used |
| revision_conflict |
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 | — |
| Stable error codes |
|---|
| invalid_install |
| platform_mismatch |
| unsupported_parameter |
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 | — |
| Stable error codes |
|---|
| creation_quota |
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 | — |
| 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/install-codes/redeem' --header 'Accept: application/json' --header 'Authorization: Bearer INSTALL_CODE' --header 'Content-Type: application/json' --data '{"installation_id":"22222222-2222-4222-8222-222222222222","name":"web-01","platform":"linux","architecture":"amd64","system_drive":"/","key_prefix":"aaaaaaaaaaaa","key_hash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","version":"vRELEASE"}'import urllib.request
headers = {'Accept': 'application/json', 'Authorization': 'Bearer INSTALL_CODE', 'Content-Type': 'application/json'}
request = urllib.request.Request('https://metribeacon.com/api/v1/agent/install-codes/redeem', headers=headers, method='POST', data='{"installation_id":"22222222-2222-4222-8222-222222222222","name":"web-01","platform":"linux","architecture":"amd64","system_drive":"/","key_prefix":"aaaaaaaaaaaa","key_hash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","version":"vRELEASE"}'.encode())
with urllib.request.urlopen(request) as response:
print(response.read().decode())
const response = await fetch("https://metribeacon.com/api/v1/agent/install-codes/redeem", {"method": "POST", "headers": {"Accept": "application/json", "Authorization": "Bearer INSTALL_CODE", "Content-Type": "application/json"}, "body": "{\"installation_id\":\"22222222-2222-4222-8222-222222222222\",\"name\":\"web-01\",\"platform\":\"linux\",\"architecture\":\"amd64\",\"system_drive\":\"/\",\"key_prefix\":\"aaaaaaaaaaaa\",\"key_hash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"version\":\"vRELEASE\"}"});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.text());
package main
import ("fmt"; "io"; "net/http"; "strings")
func main() {
req, err := http.NewRequest("POST", "https://metribeacon.com/api/v1/agent/install-codes/redeem", strings.NewReader("{\"installation_id\":\"22222222-2222-4222-8222-222222222222\",\"name\":\"web-01\",\"platform\":\"linux\",\"architecture\":\"amd64\",\"system_drive\":\"/\",\"key_prefix\":\"aaaaaaaaaaaa\",\"key_hash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"version\":\"vRELEASE\"}")); if err != nil { panic(err) }
req.Header.Set("Accept","application/json")
req.Header.Set("Authorization","Bearer INSTALL_CODE")
req.Header.Set("Content-Type","application/json")
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.
- POST Create a single-use server installation code
Browser-authorized ten-minute code bound to this workspace and selected profile. Creates no monitor until redemption; requires editor rights. Only a code hash is stored.
- GET Read automatic server setup progress
Reports receipt of the first heartbeat and selected measurements after enrollment. The issuing browser can read this status after the code expires.
- DELETE Revoke an unused installation code
Revokes an unused code. Already enrolled servers and their device keys remain managed through the existing monitor and key interfaces.