Miner telemetry publisher API

Publish measured GPU telemetry with an enrolled worker credential; keep this ingestion separate from mining, scoring and payment.

POST /api/monitoring/rl/heartbeat

This optional ingestion endpoint is for explicitly enrolled telemetry publishers. It is separate from the anonymous monitoring GET routes, the native mining protocol and account-scoped API keys. Publishing a heartbeat does not enroll a mining hotkey or affect its score or pay.

An operator must enable collection for the exact collector/network run_id supplied at enrollment (not necessarily the public trainer/catalog id) and provide a publisher alias with a distinct server-side bearer token. Send X-Reliquary-Worker with that alias, Authorization: Bearer with the publisher token, and Content-Type: application/json. No query parameters are accepted. Account keys, session cookies and hotkey signatures are not substitutes; this endpoint does not use a per-request wallet signature.

Keep the token in a private credential file or secret manager, never a web application bundle, public source, URL or log. Use HTTPS and refuse redirects. Use real runtime observations, not a fabricated inventory or copied training counters.

Payload and limits

The JSON body is limited to 24 KiB and rejects unknown fields. Required top-level fields are schema, run_id, session, seq, observed_at and devices. All listed device fields are required even when their value is null.

Observations must advance in time. Within one session counters cannot decrease. Previously observed devices cannot disappear or change hardware identity; report them offline instead. Retired sessions cannot resume. The collector is bounded to 256 enrolled publishers and 1,024 devices; enrollment is operator-managed, not a public registration API.

Field	Contract
schema	Exactly reliquary.rl-heartbeat.v1.
run_id	Exact collector/network run_id supplied at enrollment. It need not equal the public trainer/catalog id or native checkpoint namespace.
session	1–64 alphanumeric, underscore or hyphen characters. Start a new session after a process restart.
seq	Non-negative safe integer, strictly increasing within the session.
observed_at	Unix seconds, at most 30 seconds old or five seconds in the future.
devices	1–16 unique device records; send the complete retained inventory.
devices[].id / hardware_key	Stable 1–48 character alphanumeric/underscore/hyphen id; 64 lowercase hexadecimal hardware hash. Both must be unique. Do not send a raw GPU UUID.
devices[].model / status	Non-empty model name up to 128 characters; generating, idle or offline.
devices[].generated_tokens	Non-negative safe integer measured generation counter, or null.
devices[].utilization_percent	0–100, or null when not measured.
devices[].memory_used_gib / memory_total_gib	0–4096 GiB, or null. Used memory cannot exceed known total memory.
environments	Optional/null array of at most 32 unique {id, generated_groups} entries. Counters are non-negative safe integers.

Publish measured observations

With an enrolled alias, write a valid measured payload atomically to heartbeat.json and keep its publisher token separately. The following sends one existing observation; it does not generate one. Prefer the maintained publisher relay supplied with the platform integration when available: it validates payloads, refuses redirects and manages observation continuity.

One explicit telemetry write

# Requires an already enrolled telemetry publisher, not a customer API key.
: "${PUBLISHER_ALIAS:?}" "${PUBLISHER_TOKEN:?}"
curl --fail-with-body --silent --show-error --max-time 8 \
  'https://api.reliqua.ai/api/monitoring/rl/heartbeat' \
  -H "X-Reliquary-Worker: $PUBLISHER_ALIAS" \
  -H "Authorization: Bearer $PUBLISHER_TOKEN" \
  -H 'Content-Type: application/json' --data-binary @heartbeat.json

Responses and recovery

Responses use private no-store caching. Send at a bounded cadence, normally five seconds or slower; the maintained relay spaces attempts by 10–20 seconds. Two measured observations at least 10 seconds apart are needed before generation throughput can be derived.

Do not blindly resend an ambiguous write as a new sample or reset counters to bypass replay checks. Preserve session/sequence continuity and reconcile the producer state. A heartbeat acknowledgement proves neither an accepted miner submission, training consumption nor finalized payment.

HTTP	Meaning
200	{accepted:true, observed_at, heartbeat_seconds:5} after persistence. observed_at remains Unix seconds.
400 invalid_filters	Query parameters are not supported.
400 heartbeat_refused	Invalid body, run, stale timestamp, replay or inconsistent continuity.
401 unauthorized	Missing or invalid publisher alias/token.
405 method_not_allowed	Use POST.
429 heartbeat_refused	Frequency or collector queue bound exceeded; back off.
503 collector_unavailable	Collection is disabled, missing or incorrectly configured.

Public monitoring reads — Read published fleet and individual miner observations.

Miner guide — Follow the active native mining contract separately.