Cluster API

Manage cluster operations and synchronization.

GET /v1/cluster/identity

Get the cluster identity of a peer.

Authentication

None required (public endpoint).

Response

{
  "peer_id": "01HXYZ...",
  "public_key": "base64...",
  "license_id": "lic_...",
  "cluster_id": "01HABC...",
  "version": "0.1.0"
}

Example

curl http://192.168.1.10:8080/v1/cluster/identity

Use Cases

• Verify peer identity before adding
• Check license compatibility
• Retrieve public key for verification

POST /v1/cluster/init

Initialize cluster for legacy agents.

Authentication

Required. Scope: admin

Request Body

{
  "force": false
}

Response

{
  "cluster_id": "01HABC...",
  "created_by": "01HXYZ...",
  "oldest_peer_id": "01HXYZ...",
  "was_created": true,
  "message": "Cluster initialized"
}

Notes

• Only needed for agents upgraded from older versions
• New agents have clusters initialized during bootstrap
• Use force: true to regenerate cluster ID

POST /v1/cluster/sync

Trigger cluster synchronization.

Authentication

Required. Scope: admin

Response

{
  "triggered": true
}

Behavior

Triggers:

1. Gossip heartbeats to all peers
2. Configuration regeneration
3. Subsystem processing

Example

curl -X POST http://agent:8080/v1/cluster/sync \
  -H "Authorization: Bearer $TOKEN"

GET /v1/cluster/credentials

Get the shared cluster credential.

Authentication

Required. Scope: admin

Response

{
  "client_id": "cl_01HXYZ...",
  "version": 1,
  "rotated_by": "01HXYZ...",
  "rotated_at": "2024-01-15T10:30:00Z"
}

Note: client_secret is not returned.

POST /v1/cluster/credentials/rotate

Rotate the shared cluster credential.

See Credentials API for details.