API Reference

GlueArrow Box OS — Local API Document version: 1.0 · Applies to Box OS 1.6.0+ · OpenAPI 3.1

---

1. Overview

The GlueArrow Box OS engine exposes a local REST API and a Socket.IO real-time channel on TCP port 5002 of every box. This document describes the integrator-facing API surface — the stable, public endpoints intended for station automation, third-party DJ software, custom dashboards, monitoring systems, and partner integrations.

For the cloud API surface (cloud.gluearrow.com), see the separate GlueArrow Cloud API Reference.

Get the machine-readable spec:

• OpenAPI 3.1 YAML: https://gluearrow.com/openapi.yaml
• View interactively: open the YAML at https://editor.swagger.io/?url=https://gluearrow.com/openapi.yaml
• Import into Postman: Import → Link → paste the YAML URL above
• Generate clients: openapi-generator-cli generate -i https://gluearrow.com/openapi.yaml -g <language>

2. Base URL

The Box OS engine binds to all interfaces on port 5002 by default.

http://<box-address>:5002

<box-address> is the IP or hostname of the GlueArrow Box on the station LAN. On the box itself, localhost works. From other devices on the same LAN, use the box's DHCP-assigned address (visible on the 7" status LCD on Pro/Enterprise tier appliances, or via your router's DHCP table).

The API is LAN-local by design. Do not expose port 5002 to the public internet — use your station VPN or the GlueArrow Cloud dashboard for remote access. See the Network & Firewall Guide for the full network model.

3. Authentication

Three authentication methods are supported, in order of preference for different integration patterns:

Method	Header / cookie	Use case
Session cookie	Cookie: ga_session=…	Browser-based dashboards and the built-in control panel
Bearer token	Authorization: Bearer <token>	Server-to-server integrations and DJ software
No auth	—	Only /health and /metrics; restrict at the firewall layer

Bearer tokens are machine credentials bound to your box's license key, issued from the GlueArrow Cloud admin console at https://app.gluearrow.com/admin/api-tokens. Tokens are revocable instantly and rotatable without engine restart.

Failed authentication returns 401 Unauthorized. Authenticated requests lacking the required role return 403 Forbidden.

4. Versioning

The API version follows the Box OS release version. Breaking changes are introduced only in major version bumps and announced at least 90 days in advance via the release notes. Additive, non-breaking changes (new endpoints, new optional fields) may appear in any minor release.

To pin to a major version explicitly, send the Accept-Version header:

Accept-Version: 1

The current major version is 1. If omitted, the engine defaults to the latest installed version, which is the recommended behaviour for integrators tracking the latest release.

5. Rate Limits

Default limits per box, per IP, per minute:

Endpoint class	Limit
Read endpoints (GET)	600
Write endpoints (POST / PATCH / DELETE)	120
SSE streams (/api/songs/stream, /api/batch/scan/status)	4 concurrent connections per IP
Search (/api/search, /api/search/cursor)	60

Exceeded limits return 429 Too Many Requests with a Retry-After header indicating seconds to wait.

Enterprise tier customers may request higher limits via enterprise@gluearrow.com.

6. Endpoint Categories

The API is grouped into the following functional areas. Each category corresponds to a tag in the OpenAPI spec.

Category	Endpoints	Purpose
Health	/health, /metrics	Liveness probe and Prometheus exposition
State	/api/devices, /api/connectivity	Available capture devices and cloud reachability
Schedule	/api/schedule, /api/shows/*/music-clips, /api/music-clips/*	Daily broadcast schedule and music clip rundown
Streaming	/api/destinations, /api/stream/config, /api/restream/*	RTMP destinations, encoding configuration, Restream.io integration
Music	/api/music/library, /api/music/identified, /api/music/catalog, /api/music/drives, /api/songs/stream, /api/search, /api/search/cursor, /api/fingerprint/stats, /api/submit/status	Local music library, search, and submission queue status
SmartVault	/api/batch/scan/*, /api/batch/sessions, /api/batch/session/*, /api/batch/file/*	Batch music library scanning with pause/resume, incremental scans, CSV export
Ads	/api/ads/bids, /api/ads/history	Inbound ad bids, approval workflow, proof-of-play history
Artist Claims	/api/artist-claims	Royalty claim submission and tracking
Updates	/update, /api/ai-verify	Trigger OTA update check, content safety screen

For exhaustive parameter, request body, and response schema details, refer to the OpenAPI YAML.

7. Conventions

7.1 Content type

All request and response bodies use application/json unless explicitly noted (CSV exports return text/csv; SSE streams return text/event-stream; Prometheus metrics return text/plain).

7.2 Identifiers

• Numeric IDs (int64) are used for entities created and stored locally on the box (shows, music clips, ad bids, artist claims, scanned files).
• String IDs are used for cross-box identifiers (scan session IDs, cloud ad IDs).
• Track identifiers are numeric and stable for the lifetime of the local fingerprint database.

7.3 Timestamps

All timestamps are ISO 8601 UTC with millisecond precision: 2026-04-24T12:34:56.789Z. The engine relies on NTP-synchronized system time; clock skew over 2 seconds for 5 minutes triggers a health alert.

7.4 Pagination

Two pagination styles are used:

• Offset/limit (?offset=0&limit=100) — for human-browsable lists where the result set is bounded and fits in one page.
• Cursor (?after_id=…&limit=…) — for very large lists (1M+ rows) where offset-based pagination is too slow. Used by SmartVault batch session file listings and full-text search.

7.5 Errors

Error responses follow a consistent envelope:

{
  "error": "Resource not found",
  "code": "not_found",
  "request_id": "req_01J9X4P5K7VHQ2ZPKQDTQ4M0"
}

Always log request_id when filing support tickets.

8. Real-Time Events

The engine exposes a Socket.IO endpoint at ws://<box-address>:5002/socket.io/ for real-time control and state updates. Authentication is via the same session cookie or bearer token used by REST endpoints.

The Socket.IO API is not described in the OpenAPI spec because OpenAPI 3.1 does not natively model bidirectional WebSocket events. The full event schema is described below.

8.1 Server → Client events

Event	Payload	When emitted
state_update	{ source, transmission, timestamp }	Whenever the broadcast state changes (source switch, take, transition)
speaker_active	{ speaker_id, name, channel, since }	When a calibrated speaker is detected on-air
production_state	{ preview, program, on_air }	When the production bus changes
schedule_tick	{ now_show, next_show }	Every 30 seconds and on schedule changes
connectivity	{ cloud_reachable, queued }	When cloud reachability changes

8.2 Client → Server events

Event	Payload	Effect
take_cut	{}	Cut transition: program ← preview
take_fade	{ duration_ms }	Fade transition with the supplied duration
take_stinger	{ stinger_id }	Stinger transition using the named stinger
set_preview_source	{ source_id }	Set the preview bus source
set_program_source	{ source_id }	Set the program bus source (immediate take)
producer_command	{ action, payload }	Producer-desk commands (cart wall, phone lines)
caller_request	{ caller_id, line }	Mobile listener requests to call in
staff_checkin	{ user_id }	Staff member checks in at the front desk
qr_checkin	{ token }	Visitor QR check-in

8.3 Bidirectional events

Event	Payload	Direction
control_heartbeat	{ from, ts }	Liveness ping every 10 seconds; either side may originate
station_heartbeat	{ station_id, ts }	Station-level liveness for cloud monitoring

8.4 Connecting

JavaScript example (using the socket.io-client library):

import { io } from "socket.io-client";

const socket = io("http://192.168.1.50:5002", {
  auth: { token: "Bearer your-machine-token-here" },
});

socket.on("state_update", (state) => {
  console.log("Broadcast state changed:", state);
});

socket.emit("take_cut");

9. Webhooks

The Box OS engine emits webhooks to the GlueArrow Cloud (proof-of-play push, station heartbeat, ad delivery confirmation). It does not receive customer-supplied webhooks today. Customer-supplied webhook delivery is on the 2026 Q3 roadmap; the design will support replay protection (HMAC signature, monotonically increasing nonce) consistent with the rest of the security architecture.

10. Software Development Kits

GlueArrow does not currently publish official SDKs. The OpenAPI spec is the source of truth, and any of the following community generators produce working clients:

Language / Framework	Recommended generator
TypeScript / JavaScript	openapi-typescript (types only) or openapi-generator-cli with typescript-fetch
Python	openapi-python-client
Go	oapi-codegen
Java	openapi-generator-cli with java
C# / .NET	NSwag or openapi-generator-cli with csharp-netcore

If you build an open-source SDK against the GlueArrow Box OS API, we'll be happy to link to it from this page. Email enterprise@gluearrow.com.

11. Stability and Deprecation

Endpoints documented in this reference are considered stable and follow our deprecation policy: 90 days' written notice before any breaking change, with the deprecated endpoint continuing to function during the deprecation window.

Endpoints not documented here (internal admin routes, dev-only debugging routes, experimental endpoints behind feature flags) are subject to change without notice and should not be used by integrators. If you need a documented version of an undocumented endpoint, request it via enterprise@gluearrow.com.

12. Support

• Integration questions: enterprise@gluearrow.com
• Bug reports: support@gluearrow.com — include request_id and version
• Security issues: security@gluearrow.com — see Security Whitepaper § 10 for the disclosure policy

---

GlueArrow Inc. — 1111B S Governors Ave # 50266, Dover, DE 19904, United States Document identifier: GA-API-1.0 · Last reviewed: 2026-04-24