REST API

Arrivals Board includes a built-in HTTP server that accepts messages via a REST API. Any device on the same local network can post messages to the board using simple HTTP requests.

Endpoint¶

POST /api/v1/message

The base URL depends on your device's local network address. You can find the full URL in Settings > Sources > Local Server.

Typical format: http://<device-ip>:<port>/api/v1/message

Headers¶

The API key is generated automatically when you enable the local server. You can view and regenerate it in Settings > Sources > Local Server.

Request body¶

The request body is a JSON object with the following fields:

Priority levels¶

Example request body¶

{
  "text": "Build #1234 passed all tests.",
  "sender": "CI Server",
  "priority": "next",
  "indicatorColor": "green"
}

Response¶

A successful request returns:

{
  "status": "ok"
}

HTTP status code: 200 OK

Error codes¶

Error responses include a JSON body with a message field:

{
  "status": "error",
  "message": "Rate limit exceeded. Maximum 10 requests per minute."
}

Code examples¶

cURL¶

curl -X POST "http://192.168.1.42:8080/api/v1/message" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "text": "Deployment complete.",
    "sender": "Deploy Bot",
    "priority": "next",
    "indicatorColor": "green"
  }'

Python¶

import requests

response = requests.post(
    "http://192.168.1.42:8080/api/v1/message",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key-here",
    },
    json={
        "text": "Deployment complete.",
        "sender": "Deploy Bot",
        "priority": "next",
        "indicatorColor": "green",
    },
)

print(response.json())  # {"status": "ok"}

JavaScript (fetch)¶

const response = await fetch("http://192.168.1.42:8080/api/v1/message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key-here",
  },
  body: JSON.stringify({
    text: "Deployment complete.",
    sender: "Deploy Bot",
    priority: "next",
    indicatorColor: "green",
  }),
});

const data = await response.json();
console.log(data); // { status: "ok" }

Board layout endpoint¶

Automations that send messages can query the board's current layout so they can size and format text to fit. This is the same endpoint the built-in web form uses to draw its fit-ring indicator.

GET /api/v1/board-layout

No authentication required. Returns the current dimensions plus user-visible display settings as JSON.

Response fields¶

Reel type values¶

Example response¶

{
  "message_columns": 30,
  "message_rows": 9,
  "sender_columns": 20,
  "sender_rows": 1,
  "clock_display": true,
  "settings_button_display": true,
  "reel_type": "unicode_uppercase",
  "long_message_display": "truncate"
}

503 during board warm-up¶

For a brief window after the app launches — before the board view has reported its live dimensions — the endpoint returns 503 Service Unavailable:

{ "error": "Board layout not yet available. Please try again." }

Clients should retry after a short delay (e.g., 250 ms). Persisted dimensions from the previous session are restored on launch, so this window typically only appears on a truly first launch.

Diagnostics endpoint¶

For business installations and support troubleshooting, Arrivals exposes a read-only snapshot of internal source health.

GET /api/v1/diagnostics

Auth-gated by the same X-API-Key header as POST /api/v1/message. The response contains no message bodies, no auth tokens, and no PII — only counters and timestamps — so screenshots are safe to share with support.

Use cases¶

• Did a source stall? Compare each source's seconds_since_last_message against its expected polling interval (e.g., a 5-minute RSS feed should never exceed ~600 seconds).
• Is the app actually running and processing the queue? process_uptime_seconds and queue_depth confirm liveness without needing a screen on the device.
• Is sound supposed to be playing right now? When sound_hours.enabled is true, compare current_minutes against start_minutes/end_minutes.

Response fields¶

sources[]¶

sound_hours¶

Example response¶

{
  "schema_version": 1,
  "collected_at": "2026-04-29T14:00:00Z",
  "process_uptime_seconds": 7200,
  "queue_depth": 3,
  "current_message_id": "A1B2-...",
  "sources": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "display_name": "Hacker News",
      "source_type": "rss",
      "messages_received": 42,
      "stream_task_alive": true,
      "stream_started_at": "2026-04-29T12:00:00Z",
      "last_message_at": "2026-04-29T13:55:00Z",
      "seconds_since_last_message": 300
    }
  ],
  "sound_hours": {
    "enabled": true,
    "start_minutes": 480,
    "end_minutes": 1140,
    "current_minutes": 840
  }
}

Error codes¶

OAuth endpoints (Apple TV)¶

On Apple TV, signing in to services like Mastodon requires a secondary device to complete the OAuth flow. Arrivals exposes the following endpoints on the local server to facilitate this process. These are used internally by the QR code authentication system described in QR Authentication and are not intended for direct use.