> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodostatus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Heartbeat

> Send a heartbeat ping. If not received within the expected interval, the service is marked as down.

<Note>
  This endpoint requires API key authentication via the `X-API-Key` or `Authorization: Bearer` header.
</Note>

## Path Parameters

<ParamField path="monitorId" type="string" required>
  The heartbeat monitor ID
</ParamField>

## Body Parameters

<ParamField body="status" type="string" default="up">
  Status to report: `up`, `down`, `degraded`
</ParamField>

<ParamField body="response_time_ms" type="integer">
  Execution time in milliseconds
</ParamField>

<ParamField body="message" type="string">
  Optional status message
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the heartbeat was recorded
</ResponseField>

<ResponseField name="recorded_at" type="string">
  ISO 8601 timestamp
</ResponseField>

<ResponseField name="monitor_status" type="string">
  Current monitor status
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://kodostatus.com/api/heartbeat/hb_abc123" \
    -H "X-API-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "up",
      "response_time_ms": 1523,
      "message": "Backup completed successfully"
    }'
  ```

  ```bash Simple ping theme={null}
  # Just ping without body
  curl -X POST "https://kodostatus.com/api/heartbeat/hb_abc123" \
    -H "X-API-Key: your_api_key"
  ```

  ```javascript Node.js theme={null}
  // At the end of your cron job
  await fetch('https://kodostatus.com/api/heartbeat/hb_abc123', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.KODO_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'up',
      response_time_ms: Date.now() - startTime
    })
  });
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      'https://kodostatus.com/api/heartbeat/hb_abc123',
      headers={'X-API-Key': 'your_api_key'},
      json={'status': 'up', 'message': 'Job completed'}
  )
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "recorded_at": "2024-01-15T10:30:00Z",
    "monitor_status": "up"
  }
  ```
</ResponseExample>