Device Agent Endpoints

All Device Agent routes use POST and are relative to {probo-origin}/api/agent/v1.

Endpoint	Authentication	Success response
`/enroll`	Enrollment token in body	`200` JSON
`/heartbeat`	Device API key	`200` JSON
`/postures`	Device API key	`204`
`/unenroll`	Device API key	`204`

Request headers

Send these titles with each application:

Accept: application/json
Content-Type: application/json
User-Agent: my-probo-agent/1.0.0

For each route, except for /enroll, also send:

Authorization: Bearer <device-api-key>

User-Agent is recommended for troubleshooting and is not used for authentication.

Enroll

Change a sign-up token with a single hit for an API key.

POST /api/agent/v1/enroll

The body of the request is limited to 16 KiB.

Request

{
  "token": "<enrollment-token>"
}

Field	Type	Required	Description
`token`	string	Yes	One-shot enrollment token

Response

200 OK

{
  "api_key": "<device-api-key>"
}

Safe storage of the key before starting the service. the sign-up token is deleted after a successful exchange and cannot be reused.

Heartbeat

Report the device identity and retrieve the reporting program. The first successful heart rate changes a device PENDING into ACTIVE. Heart rate and posture intervals are independent; update each local timer in the response.

POST /api/agent/v1/heartbeat
Authorization: Bearer <device-api-key>

The body of the request is limited to 16 KiB.

Request

{
  "hardware_uuid": "example-hardware-id",
  "serial_number": "example-serial-number",
  "hostname": "example-device",
  "platform": "LINUX",
  "os_version": "Example Linux 1.0",
  "agent_version": "1.0.0"
}

Field	Type	Required	Description
`hardware_uuid`	string	Yes	Stable hardware identifier
`serial_number`	string	No	Hardware serial number
`hostname`	string	Yes	Current device hostname
`platform`	string	Yes	One of the platform values accepted below
`os_version`	string	Yes	Human-readable operating-system version
`agent_version`	string	Yes	Implementation version of the reporting agent

The valid values ___ZBT_I18N_RUNTIME_BLOCK_202__ are:

Value	Platform
`DARWIN`	macOS
`LINUX`	Linux
`FREEBSD`	FreeBSD
`WINDOWS`	Windows

The UUID of the hardware must be stable throughout the restart. the platform rejects activation if another device in the organization already uses it.

Response

200 OK

{
  "device_id": "<device-id>",
  "heartbeat_interval_seconds": 300,
  "posture_interval_seconds": 3600,
  "server_time": "2026-08-05T14:00:00Z"
}

Field	Type	Description
`device_id`	string	the platform identifier for the registered device
`heartbeat_interval_seconds`	integer	Delay between heartbeat requests
`posture_interval_seconds`	integer	Delay between posture collection cycles
`server_time`	string	Current server time in RFC 3339 UTC format

Treat the answer as authoritative: update each local timer after each successful heartbeat, instead of encoding those values or assuming the programs remain in place.

Postures

Calls for a series of locally evaluated posture checks. The device must have passed a heartbeat before reporting the posture. A posture application while the device is still PENDING returns 401 Unauthorized – the same status used for revocation – so first activate with /heartbeat.

POST /api/agent/v1/postures
Authorization: Bearer <device-api-key>

The request body is limited to 1 MiB and can contain up to 100 results.

Request

{
  "results": [
    {
      "check_key": "FIREWALL_ENABLED",
      "status": "PASS",
      "evidence": {
        "backend": "ufw",
        "raw": "Status: active"
      },
      "observed_at": "2026-08-05T14:00:00Z"
    }
  ]
}

Field	Type	Required	Description
`results`	array	Yes	Up to 100 posture results
`check_key`	string	Yes	Identificator stabil pentru verificare
`status`	string	Yes	Result status
`evidence`	JSON object	No	Details supporting the result
`observed_at`	string	Yes	Observation time in RFC 3339 format
`correlation_id`	string	No	The platform’s posture-report ID used to group the associated result sets

A blank matrix results is accepted as non-op. A successful request returns 204 No Content.

Status values

Value	Meaning
`PASS`	The check passed
`FAIL`	The check failed
`UNKNOWN`	Agentul nu a putut stabili rezultatul
`NOT_APPLICABLE`	This verification does not apply to this device.

Canonical check keys

Use official keys when your check has the same meaning.This allows the platform to interpret and display evidence consistently.

Check key	What it evaluates
`DISK_ENCRYPTION`	Full-disk encryption
`SCREEN_LOCK`	Screen or idle-lock configuration
`FIREWALL_ENABLED`	Host firewall
`TIME_SYNC`	System clock synchronization
`OS_VERSION`	Operating-system version
`AUTO_UPDATE`	Automatic operating-system updates
`PASSWORD_POLICY`	Local password policy
`REMOTE_LOGIN`	Remote-login exposure
`MALWARE_PROTECTION`	Built-in malware protection

APIaccepts other unfilled verification keys, but the platform may display their evidence as unknown.

Evidence

The evidence is JSON in free form. Prefer an object with concise fields that can be machine read. Do not include secrets, complete configuration files, or command outputs that may contain personal or sensitive data.

Official agent evidence schemes are the best reference when implementing a canonical verification. checks package.

Correlation IDs

If correlation_id is omitted, the platform creates an ID and applies it to each result in the application.

Provide a correlation ID only when you already have a valid platform device position reporting ID for the same tenant. invalid IDs, IDs for another entity type and IDs from another tenant return 400 Bad Request.

Unenroll

Revokes the current device API key.

POST /api/agent/v1/unenroll
Authorization: Bearer <device-api-key>

No application fields are required. A successful application returns 204 No Content. Delete local credentials regardless of whether this application with the best effort succeeds during uninstallation.

Errors

Status	Meaning
`400`	Invalid JSON, missing fields, invalid enum or over-sized batch
`401`	Invalid registration token, API keyInvalid/invalid, revocation or posture before activation
`405`	The route was called by a method other than `POST`
`500`	Unexpected server error

Do not rely on the exact error message. Record the status and context of the secure request without recording credentials or proof of posture. Retrify temporary network failures and answers ___ZBT_I18N_RUNTIME_BLOCK_258__ with exponentially limited backlinks. Do not retrify answers ___ZBT_I18N_RUNTIME_BLOCK_259__ without changing the request and Clear credentials by 401 unless a posture application precedes the first successful heartbeat.