Device Agent Endpoints

All Device Agent API 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 headers with every request:

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

For every route except /enroll, also send:

Authorization: Bearer <device-api-key>

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

Enroll

Exchanges a one-shot enrollment token for a device API key.

POST /api/agent/v1/enroll

The request body 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>"
}

Store the key securely before starting the service. The enrollment token is deleted after a successful exchange and cannot be reused.

Heartbeat

Reports the device identity and retrieves its reporting schedule. The first successful heartbeat changes a PENDING device to ACTIVE. Heartbeat and posture intervals are independent; update each local timer from the response.

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

The request body 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 supported platform values below
os_version	string	Yes	Human-readable operating-system version
agent_version	string	Yes	Version of the reporting agent implementation

Valid platform values are:

Value	Platform
DARWIN	macOS
LINUX	Linux
FREEBSD	FreeBSD
WINDOWS	Windows

The hardware UUID must be stable across restarts. Probo 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	Probo identifier for the enrolled 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

The current defaults are 300 seconds for heartbeats and 3,600 seconds for posture collection. Treat the response as authoritative: update each local timer after every successful heartbeat instead of hard-coding these values or assuming the schedules stay in lockstep.

Postures

Pushes a batch of locally evaluated posture checks. The device must have sent a successful heartbeat before reporting posture. A posture request while the device is still PENDING returns 401 Unauthorized—the same status used for revocation—so activate with /heartbeat first.

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

The request body is limited to 1 MiB and can contain at most 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	Stable identifier for the check
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	Probo posture-report ID used to group related result sets

An empty results array is accepted as a no-op. A successful request returns 204 No Content.

Status values

Value	Meaning
PASS	The check passed
FAIL	The check failed
UNKNOWN	The agent could not determine the result
NOT_APPLICABLE	The check does not apply to this device

Canonical check keys

Use the official keys when your check has the same meaning. This allows Probo to interpret and display the 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

The API accepts other non-empty check keys, but Probo might display their evidence as unknown. Use a stable uppercase identifier and keep its semantics consistent across agent versions.

Evidence

Evidence is free-form JSON. Prefer an object with concise machine-readable fields. Do not include secrets, full configuration files, or command output that might contain personal or sensitive data.

The official agent’s evidence schemas are the best reference when implementing a canonical check. See the checks package.

Correlation IDs

Results from one collection cycle should belong to one posture report. If correlation_id is omitted, Probo creates one ID and applies it to every result in the request.

Only provide a correlation ID when you already have a valid Probo device-posture-report 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 request fields are required. A successful request returns 204 No Content. Delete local credentials whether or not this best-effort request succeeds during uninstall.

Errors

Status	Meaning
400	Invalid JSON, missing fields, invalid enum, or oversized batch
401	Invalid enrollment token, missing/invalid API key, revocation, or posture before activation
405	The route was called with a method other than POST
500	Unexpected server error

Do not depend on the exact error message. Log the status and safe request context without logging credentials or posture evidence. Retry temporary network failures and 5xx responses with bounded exponential backoff. Do not retry 400 responses without changing the request, and clear credentials after 401 except during bring-up when a posture request precedes the first successful heartbeat.