---
title: "Api Byoc Heartbeat Create"
method: POST
path: "/api/byoc/heartbeat/"
tags: ["platformApi"]
---

# Api Byoc Heartbeat Create

`POST /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.

## Headers

- `X-Respan-Deployment-Token` string, required

## Request body

- HeartbeatRequestRequest — Request body for POST /api/byoc/heartbeat/ — optional telemetry.
  - `telemetry` TelemetryRequest — 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.
    - `schema_version` integer
    - `app_version` string
    - `metrics` object

## Response `200`

- HeartbeatResponse — Response for POST /api/byoc/heartbeat/ (mirrors ``process_heartbeat``).
  - `state` string, required — Entitlement state machine value.
  - `is_entitled` boolean, required
  - `note` string, nullable, required
  - `license_key` string, nullable, required — Fresh entitlement token; null when not entitled.
  - `token_expires_at` string, date-time, nullable, required
  - `grace_days` integer, required
  - `next_heartbeat_seconds` integer, required

## Other responses

- `401` — Invalid or missing deployment service token.

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/versions/c26d550029f8/schema)