MetriBeacon
Menu

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

FieldType and limitsRequiredMeaning
$AgentInstallClaimYes—
$.installation_idstringYesInstallation setting or machine-reported value.
$.namestringYesInstallation setting or machine-reported value.
$.platformstringYesInstallation setting or machine-reported value.
$.architecturestringYesInstallation setting or machine-reported value.
$.system_drivestringYesInstallation setting or machine-reported value.
$.key_prefixstringYesInstallation setting or machine-reported value.
$.key_hashstringYesInstallation setting or machine-reported value.
$.versionstringYesInstallation setting or machine-reported value.
$.expected_account_idstringNoInstallation setting or machine-reported value.
$.setup_targetsarray<object>; {"minItems":2,"maxItems":200}NoAutomatically 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[]objectYes—
$.setup_targets[].addressstringNo—
$.setup_targets[].familystringNo—
$.setup_targets[].idstringYesUUID of this resource. Keep the returned identifier for subsequent operations.
$.setup_targets[].kindstringYesResource kind or measurement type selected from the listed values.
$.setup_targets[].labelstring; {"maxLength":128,"minLength":1}YesDisplay name for the component.
$.setup_targets[].local_refstringNo—
$.setup_targets[].namestringNoHuman-readable resource name. Follow the listed length limit.
$.setup_targets[].pathstring; {"maxLength":1024}No—
$.setup_targets[].portintegerNo—
$.setup_targets[].projectstringNo—
$.setup_targets[].protocolstringNo—
$.setup_targets[].text_languagesobjectNo—
$.setup_targets[].timeout_secondsintegerNo—
$.setup_targets[].translationsobject; {"additionalProperties":false}No—
$.setup_targets[].translations.deobjectNo—
$.setup_targets[].translations.enobjectNo—
$.setup_targets[].transportstringNo—
$.setup_targets[].filesystem_identitystring; {"maxLength":256}NoAgent-reported volume identity. Keep it unchanged to prevent a replacement volume from continuing another volume’s history.
$.setup_targets[].disk_identitystring; {"maxLength":256}No—
$.system_inventoryobject; {"additionalProperties":false}No—
$.system_inventory.versioninteger; {"enum":[1]}Yes—
$.system_inventory.disks_knownbooleanYes—
$.system_inventory.disksarray<object; {"additionalProperties":false}>; {"maxItems":200}Yes—
$.system_inventory.disks[]object; {"additionalProperties":false}Yes—
$.system_inventory.disks[].component_idstring; {"maxLength":192}Yes—
$.system_inventory.disks[].pathstring; {"maxLength":1024}Yes—
$.system_inventory.disks[].labelstring; {"maxLength":128}Yes—
$.system_inventory.disks[].identitystring; {"maxLength":256}Yes—
$.system_inventory.swap_activeboolean | nullYes—
$.system_inventory.process_count_availablebooleanYes—
$.system_inventory.disk_ioLogicalDiskIOInventory | nullNo—
$.system_inventory.disk_io (anyOf 1)LogicalDiskIOInventoryNo—
$.system_inventory.disk_io (anyOf 1).completebooleanYes—
$.system_inventory.disk_io (anyOf 1).disk_count_knownbooleanYes—
$.system_inventory.disk_io (anyOf 1).disk_countinteger; {"minimum":0,"maximum":200}Yes—
$.system_inventory.disk_io (anyOf 1).source_countinteger; {"minimum":0,"maximum":1024}Yes—
$.system_inventory.disk_io (anyOf 1).source_setstring; {"maxLength":64}Yes—
$.system_inventory.disk_io (anyOf 2)nullNo—
$.system_inventory.healthServerHealthInventory | nullNo—
$.system_inventory.health (anyOf 1)ServerHealthInventoryNo—
$.system_inventory.health (anyOf 1).versioninteger; {"const":1}Yes—
$.system_inventory.health (anyOf 1).sourcesarray<ServerHealthSource>; {"maxItems":1200}Yes—
$.system_inventory.health (anyOf 1).sources[]ServerHealthSourceYes—
$.system_inventory.health (anyOf 1).sources[].componentServerComponentYes—
$.system_inventory.health (anyOf 1).sources[].component.addressstringNo—
$.system_inventory.health (anyOf 1).sources[].component.familystringNo—
$.system_inventory.health (anyOf 1).sources[].component.idstringYesUUID of this resource. Keep the returned identifier for subsequent operations.
$.system_inventory.health (anyOf 1).sources[].component.kindstringYesResource kind or measurement type selected from the listed values.
$.system_inventory.health (anyOf 1).sources[].component.labelstringYesDisplay name for the component.
$.system_inventory.health (anyOf 1).sources[].component.local_refstringNo—
$.system_inventory.health (anyOf 1).sources[].component.namestringNoHuman-readable resource name. Follow the listed length limit.
$.system_inventory.health (anyOf 1).sources[].component.pathstringNo—
$.system_inventory.health (anyOf 1).sources[].component.portintegerNo—
$.system_inventory.health (anyOf 1).sources[].component.projectstringNo—
$.system_inventory.health (anyOf 1).sources[].component.protocolstringNo—
$.system_inventory.health (anyOf 1).sources[].component.text_languagesobjectNo—
$.system_inventory.health (anyOf 1).sources[].component.timeout_secondsintegerNo—
$.system_inventory.health (anyOf 1).sources[].component.translationsobject; {"additionalProperties":false}No—
$.system_inventory.health (anyOf 1).sources[].component.translations.deobjectNo—
$.system_inventory.health (anyOf 1).sources[].component.translations.enobjectNo—
$.system_inventory.health (anyOf 1).sources[].component.transportstringNo—
$.system_inventory.health (anyOf 1).sources[].component.filesystem_identitystring; {"maxLength":256}NoAgent-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_identitystring; {"maxLength":256}No—
$.system_inventory.health (anyOf 1).sources[].groupstring; {"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[].statusstring; {"enum":["ready","unsupported","permission_denied","failed"]}Yes—
$.system_inventory.health (anyOf 1).sources[].minimum_interval_secondsinteger; {"minimum":1,"maximum":86400}Yes—
$.system_inventory.health (anyOf 2)nullNo—

Responses

application/json

FieldType and limitsRequiredMeaning
$AgentInstallReceiptYes—
$.account_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.workspace_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.device_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.key_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.replayedbooleanYesInstallation setting or machine-reported value.

application/json

FieldType and limitsRequiredMeaning
$AgentInstallReceiptYes—
$.account_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.workspace_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.device_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.key_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.replayedbooleanYesInstallation setting or machine-reported value.
Stable error codes
invalid_install

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
forbidden

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
not_found

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
install_used
revision_conflict

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
invalid_install
platform_mismatch
unsupported_parameter

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
creation_quota

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
unavailable

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"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.

shell
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"}'
python
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())
javascript
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());
go
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)
}