Peers API
Peer management endpoints
Peers API
Manage cluster peers.
GET /v1/peers
List all peers.
Authentication
Required. Scope: peers.read
Query Parameters
| Parameter | Type | Description |
|---|---|---|
is_local | boolean | Filter by local status |
Response
[
{
"id": "01HXYZ...",
"name": "Agent A",
"public_key": "base64...",
"is_local": true,
"address": "192.168.1.10:8080",
"created_at": "2024-01-15T10:30:00Z"
}
]Example
curl -X GET http://agent:8080/v1/peers \
-H "Authorization: Bearer $TOKEN"
# Filter to remote peers
curl -X GET "http://agent:8080/v1/peers?is_local=false" \
-H "Authorization: Bearer $TOKEN"GET /v1/peers/{id}
Get a specific peer.
Authentication
Required. Scope: peers.read
Path Parameters
| Parameter | Description |
|---|---|
id | Peer ID |
Response
{
"id": "01HXYZ...",
"name": "Agent A",
"public_key": "base64...",
"is_local": true,
"address": "192.168.1.10:8080",
"created_at": "2024-01-15T10:30:00Z"
}Errors
| Status | Code | Description |
|---|---|---|
| 404 | NOT_FOUND | Peer not found |
POST /v1/peers
Add a remote peer.
Authentication
Required. Scope: peers.write
Request Body
{
"address": "192.168.1.20:8080"
}| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Peer address (host:port) |
Response
{
"id": "01HXYZ...",
"name": "",
"public_key": "base64...",
"is_local": false,
"address": "192.168.1.20:8080",
"created_at": "2024-01-15T10:30:00Z"
}Errors
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Missing address |
| 409 | ALREADY_EXISTS | Peer already in cluster |
| 422 | HANDSHAKE_FAILED | Handshake failed |
| 422 | NODE_LIMIT_EXCEEDED | License limit reached |
| 422 | LICENSE_MISMATCH | Different licenses |
Example
curl -X POST http://agent:8080/v1/peers \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"address": "192.168.1.20:8080"}'PUT /v1/peers/{id}
Update peer metadata.
Authentication
Required. Scope: peers.write
Path Parameters
| Parameter | Description |
|---|---|
id | Peer ID |
Request Body
{
"name": "Production Server 1"
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | New peer name |
Response
{
"id": "01HXYZ...",
"name": "Production Server 1",
"public_key": "base64...",
"is_local": false,
"address": "192.168.1.20:8080",
"created_at": "2024-01-15T10:30:00Z"
}Errors
| Status | Code | Description |
|---|---|---|
| 404 | NOT_FOUND | Peer not found |
DELETE /v1/peers/{id}
Delete a peer.
Authentication
Required. Scope: peers.write
Path Parameters
| Parameter | Description |
|---|---|
id | Peer ID |
Response
{
"deleted": true
}Errors
| Status | Code | Description |
|---|---|---|
| 404 | NOT_FOUND | Peer not found |
| 422 | CANNOT_DELETE_LOCAL | Use /v1/peers/self |
DELETE /v1/peers/self
Remove the local peer from the cluster.
Authentication
Required. Scope: admin
Response
{
"peer_id": "01HXYZ...",
"version": 2,
"is_active": false,
"deactivated_at": "2024-01-15T10:30:00Z"
}Notes
- Broadcasts deactivation to all cluster peers
- Services involving this peer become inactive