The Web API lets you and third-party tools act on a clock you own. Right now it has one endpoint: posting a note.

If, instead, you are writing firmware for a clock itself, you want the Device API.

Usage#

Endpoints

The root for all Web API endpoints is https://poem.town/api/v1.

Authorization

Each clock has its own Web API token. Generate one from your dashboard: Dashboard → your clock → Web API. You can copy, rotate, or delete it from the same screen.

Pass the token in the Authorization header:

Authorization: Bearer poem_yourTokenHere

Tokens are per-clock. A token authorises actions on the clock it was generated for, and no other. If you transfer ownership of a clock (by unclaiming it), the token is revoked.

Request and response format

All requests are made using HTTP POST with a JSON body. Responses are JSON.

Datetimes always use ISO8601 without milliseconds and with an explicit Z, e.g. 2025-01-03T16:49:10Z.

/notes#

Post a note to a clock. The note will appear on the screen the next time the clock checks in.

Example

curl \
  -H "Authorization: Bearer poem_yourTokenHere" \
  --json '{"screenId": "80AB412341234", "body": "Hello clock!"}' \
  https://poem.town/api/v1/notes

Request

The request body must include screenId (the 40-character screen ID of the clock the token belongs to) and body (the note text).

{
  "screenId": "80AB412341234", // string
  "body": "Hello clock!" // string, 1 to 140 characters
}

Response

A 201 Created is returned on success, with the note ID and the time the note was posted.

{
  "success": true, // boolean
  "note": {
    "id": "123", // string
    "postedAt": "2026-05-25T18:00:00Z" // string, ISO date
  }
}

A 401 Unauthorized is returned if the token is missing, malformed, or does not match the clock identified by screenId.

A 422 Unprocessable Entity is returned if the request body fails validation: missing field, empty body, or body longer than 140 characters.

(POST only — other HTTP methods return 405 Method Not Allowed.)