MetriBeacon
Menu

POST Create a single-use server installation code

/api/v1/agent/install-codes

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.

On this page

Access and permissions

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.

Browser session: __Host-mb_session cookie.

Parameters and headers

No path, query or additional request-header parameters.

Request body

FieldType and limitsRequiredMeaning
$AgentInstallSettingsYes—
$.workspace_idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.device_idstring; {"format":"uuid"}NoInstallation setting or machine-reported value.
$.namestringNoInstallation setting or machine-reported value.
$.platformstring; {"enum":["unix","windows"]}YesInstallation setting or machine-reported value.
$.template_idstring; {"const":"server_nas"}YesInstallation setting or machine-reported value.
$.group_idsarray<string; {"format":"uuid"}>; {"maxItems":100}YesInstallation setting or machine-reported value.
$.group_ids[]string; {"format":"uuid"}Yes—
$.interval_secondsinteger; {"minimum":1,"maximum":86400,"default":10}YesInstallation setting or machine-reported value.
$.server_profileServerProfileNo—
$.server_profile.componentsarray<object>; {"maxItems":200} | nullYesDiscovered or explicitly selected server components.
$.server_profile.components (anyOf 1)array<object>; {"maxItems":200}No—
$.server_profile.components (anyOf 1)[]objectYes—
$.server_profile.components (anyOf 1)[].addressstringNo—
$.server_profile.components (anyOf 1)[].familystringNo—
$.server_profile.components (anyOf 1)[].idstringYesUUID of this resource. Keep the returned identifier for subsequent operations.
$.server_profile.components (anyOf 1)[].kindstringYesResource kind or measurement type selected from the listed values.
$.server_profile.components (anyOf 1)[].labelstring; {"maxLength":128,"minLength":1}YesDisplay name for the component.
$.server_profile.components (anyOf 1)[].local_refstringNo—
$.server_profile.components (anyOf 1)[].namestringNoHuman-readable resource name. Follow the listed length limit.
$.server_profile.components (anyOf 1)[].pathstring; {"maxLength":1024}No—
$.server_profile.components (anyOf 1)[].portintegerNo—
$.server_profile.components (anyOf 1)[].projectstringNo—
$.server_profile.components (anyOf 1)[].protocolstringNo—
$.server_profile.components (anyOf 1)[].text_languagesobjectNo—
$.server_profile.components (anyOf 1)[].timeout_secondsintegerNo—
$.server_profile.components (anyOf 1)[].translationsobject; {"additionalProperties":false}No—
$.server_profile.components (anyOf 1)[].translations.deobjectNo—
$.server_profile.components (anyOf 1)[].translations.enobjectNo—
$.server_profile.components (anyOf 1)[].transportstringNo—
$.server_profile.components (anyOf 1)[].filesystem_identitystring; {"maxLength":256}NoAgent-reported volume identity. Keep it unchanged to prevent a replacement volume from continuing another volume’s history.
$.server_profile.components (anyOf 1)[].disk_identitystring; {"maxLength":256}No—
$.server_profile.components (anyOf 2)nullNo—
$.server_profile.selectionsarray<object>; {"maxItems":200} | nullYesSelected component/parameter pairs and sampling intervals.
$.server_profile.selections (anyOf 1)array<object>; {"maxItems":200}No—
$.server_profile.selections (anyOf 1)[]objectYes—
$.server_profile.selections (anyOf 1)[].component_idstringYesStable identifier of the selected or discovered component.
$.server_profile.selections (anyOf 1)[].interval_secondsinteger; {"maximum":86400,"minimum":0}YesSampling or check interval in seconds within the stated bounds.
$.server_profile.selections (anyOf 1)[].parameter_keystringYesStable parameter identifier from the server catalog.
$.server_profile.selections (anyOf 2)nullNo—
$.server_profile.versionJSON; {"const":2}Yes—
$.server_profile.overviewobject; {"additionalProperties":false}NoExplicit targets for the six-chart server overview; select all required readings.
$.server_profile.overview.system_idstring; {"maxLength":128}Yes—
$.server_profile.overview.filesystem_idstring; {"maxLength":128}Yes—
$.server_profile.overview.disk_idstring; {"maxLength":128}Yes—
$.server_profile.overview.network_idstring; {"maxLength":128}Yes—
$.server_profile.overview.platformstring; {"enum":["linux","darwin","windows"]}NoPlatform of the automatic overview. Only supported metrics are selected; undetected disk or network targets stay empty.
$.server_profile.filesystem_discoveryobject; {"additionalProperties":false}NoOptional 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.modestring; {"enum":["off","local"]}Yes—
$.server_profile.filesystem_discovery.interval_secondsinteger; {"minimum":10,"maximum":86400}Yes—
$.server_profile.system_discoveryobject; {"additionalProperties":false}No—
$.server_profile.system_discovery.modestring; {"enum":["off","local"]}Yes—
$.server_profile.system_discovery.interval_secondsinteger; {"minimum":10,"maximum":86400}Yes—
$.server_profile.disk_io_interval_secondsinteger; {"minimum":1,"maximum":86400}No—
$.server_profile.global_interval_secondsinteger; {"minimum":1,"maximum":86400}NoExplicit global sampling choice. Each source still applies its platform minimum; individual fast rows never imply this choice.

Responses

application/json

FieldType and limitsRequiredMeaning
$AgentInstallCodeYes—
$.idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.install_codestringYesInstallation setting or machine-reported value.
$.expires_atstring; {"format":"date-time"}YesInstallation setting or machine-reported value.
$.versionstringYesInstallation setting or machine-reported value.

application/json

FieldType and limitsRequiredMeaning
$AgentInstallCodeYes—
$.idstring; {"format":"uuid"}YesInstallation setting or machine-reported value.
$.install_codestringYesInstallation setting or machine-reported value.
$.expires_atstring; {"format":"date-time"}YesInstallation setting or machine-reported value.
$.versionstringYesInstallation setting or machine-reported value.

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
invalid_install
invalid_profile
invalid_groups

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_limit
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
release_unavailable
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' --header 'Accept: application/json' --header 'Cookie: __Host-mb_session=YOUR_SESSION; __Host-mb_csrf=YOUR_CSRF' --header 'Origin: https://metribeacon.com' --header 'X-CSRF-Token: YOUR_CSRF' --header 'Content-Type: application/json' --data '{"workspace_id":"11111111-1111-4111-8111-111111111111","template_id":"server_nas","platform":"unix","group_ids":[],"interval_seconds":30}'
python
import urllib.request
headers = {'Accept': 'application/json', 'Cookie': '__Host-mb_session=YOUR_SESSION; __Host-mb_csrf=YOUR_CSRF', 'Origin': 'https://metribeacon.com', 'X-CSRF-Token': 'YOUR_CSRF', 'Content-Type': 'application/json'}
request = urllib.request.Request('https://metribeacon.com/api/v1/agent/install-codes', headers=headers, method='POST', data='{"workspace_id":"11111111-1111-4111-8111-111111111111","template_id":"server_nas","platform":"unix","group_ids":[],"interval_seconds":30}'.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", {"method": "POST", "headers": {"Accept": "application/json", "Cookie": "__Host-mb_session=YOUR_SESSION; __Host-mb_csrf=YOUR_CSRF", "Origin": "https://metribeacon.com", "X-CSRF-Token": "YOUR_CSRF", "Content-Type": "application/json"}, "body": "{\"workspace_id\":\"11111111-1111-4111-8111-111111111111\",\"template_id\":\"server_nas\",\"platform\":\"unix\",\"group_ids\":[],\"interval_seconds\":30}"});
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", strings.NewReader("{\"workspace_id\":\"11111111-1111-4111-8111-111111111111\",\"template_id\":\"server_nas\",\"platform\":\"unix\",\"group_ids\":[],\"interval_seconds\":30}")); 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("Origin","https://metribeacon.com")
 req.Header.Set("X-CSRF-Token","YOUR_CSRF")
 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)
}