---
title: "Register device availability"
method: POST
path: "/v1/device-requests/heartbeat"
tags: ["Conversations"]
---

# Register device availability

`POST /v1/device-requests/heartbeat`

## Request

- Base URL: `https://api.shardflux.dev`
- URL: `https://api.shardflux.dev/v1/device-requests/heartbeat`
- Auth: HTTP bearer

## Request body

- object
  - `project_id` string, uuid: UUIDv7, lowercase canonical form.
  - `device_id` string, required
  - `lease_seconds` integer
  - `conversation_ids` string[]: This device’s local conversations of the project (started from it, or opened on it): their device requests come here first.
  - `device` object: This computer, for your list of computers (GET /v1/devices). Sent by the Shard app and `shard` with each heartbeat.
    - `capabilities` string[]
    - `name` string: The computer’s own name (“Jonne’s MacBook Pro”). A name the person chose stays.
    - `os` string: “macOS 26.4”, “Ubuntu 24.04.1 LTS”.
    - `machine_id` string: sha256 of the computer’s hardware id (IOPlatformUUID, /etc/machine-id) salted with your user id, computed on the computer: the raw id never leaves it. The same computer under a new device id stays one computer.
    - `approvals` 'auto' | 'read' | 'ask'
    - `replaces` string[]: Device ids this computer used before. They are retired: their waiting requests come to this one.

## Response `200`

Default Response

- object
  - `device_id` string, required
  - `online_until` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `device` object: This computer as your list of computers shows it.
    - `device_id` string, required
    - `name` string, required
    - `approvals` 'auto' | 'read' | 'ask', nullable, required
    - `retired` string[], required: The device ids this heartbeat retired (the same computer before).

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)