Api Byoc Heartbeat Create

POST

https://api.respan.ai/api/byoc/heartbeat/

Data-plane heartbeat — authenticated by the deployment service token.

Authenticated by X-Respan-Deployment-Token (not a user JWT), so it has no JWT auth/permission classes; resolve_deployment_by_token is the gate.

Authentication

X-Respan-Deployment-Tokenstring

BYOC data-plane deployment service token (issued at registration; not a user JWT)

Request

This endpoint expects an object.

telemetryobjectOptional

Health/usage telemetry the data plane reports with a heartbeat.

The payload is customer-data-plane-controlled, so every field is bounded and only known keys survive — metrics is a small map of named numeric gauges (request counts, indexing lag, …) the data plane can extend without a schema change, capped so a compromised/misconfigured plane can’t bloat storage.

Response

statestring

Entitlement state machine value.

is_entitledboolean

notestring or null

license_keystring or null

Fresh entitlement token; null when not entitled.

token_expires_atdatetime or null

grace_daysinteger

next_heartbeat_secondsinteger

Errors

401

Unauthorized Error

$	curl -X POST https://api.respan.ai/api/byoc/heartbeat/ \
>	-H "X-Respan-Deployment-Token: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"state": "string",
3	"is_entitled": true,
4	"note": "string",
5	"license_key": "string",
6	"token_expires_at": "2024-01-15T09:30:00Z",
7	"grace_days": 1,
8	"next_heartbeat_seconds": 1
9	}