Node Management API Specification
RESTful diagnostic and telemetry coordination API for registered CI/CD build runner workers and automated monitoring agents.
Authentication & Security Policy
All requests to the management endpoint require cryptographic token authorization:
Bearer Token Header Requirement
Every HTTP transaction must present an authenticated token in the standard HTTP header:
Authorization: Bearer <CRYPTOGRAPHIC_BEARER_TOKEN>
Unauthenticated Access: Requests omitting or presenting invalid tokens immediately receive an HTTP 401 Unauthorized response.
Rate Limiting: Enforced at 120 requests per minute per Bearer token. Exceeding requests receive an HTTP 429 Too Many Requests with a Retry-After header.
Route Specification
GET /api/v1/status
Queries real-time node operational status, active runner sessions, and cache engine status.
curl -sS https://api.runner-fra1.test-pr.space/api/v1/status \
-H "Authorization: Bearer sec_tok_420560"
Sample Response (200 OK):
{
"service": "testpr-edge",
"status": "operational",
"region": "fra1",
"timestamp": 1726070400,
"sessions_active": 428
}
POST /api/v1/artifacts/lookup
Queries CAS storage availability for a list of SHA-256 binary action cache digests.
curl -sS -X POST https://api.runner-fra1.test-pr.space/api/v1/artifacts/lookup \
-H "Authorization: Bearer sec_tok_420560" \
-H "Content-Type: application/json" \
-d '{"hashes":["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]}'
Sample Response (200 OK):
{
"available": [
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
],
"missing": []
}
GET /api/v1/sync/peers
Returns active QUIC inter-node replication mesh status and topological round-trip latency.
curl -sS https://api.runner-fra1.test-pr.space/api/v1/sync/peers \
-H "Authorization: Bearer sec_tok_420560"
Sample Response (200 OK):
{
"node": "runner-fra1",
"peers": [
{"node": "runner-ams1", "rtt_ms": 0.3, "quic_state": "ESTABLISHED"},
{"node": "runner-lon1", "rtt_ms": 0.5, "quic_state": "ESTABLISHED"}
]
}