PTT Public API

Version 1.0.0

REST API for managing PTT rooms, streaming event logs, and injecting server-side broadcasts into live channels. Base URL: https://ptt.606.co.il/api/public/v1

צריך מפתח API?

הירשם או התחבר כדי ליצור ולנהל מפתחות מתוך הממשק.

צור מפתח API

Authentication

Send your API key in the x-api-key header. Keys are prefixed ptt_… and have one or more scopes: read, write, admin.

curl -H "x-api-key: ptt_xxxxxxxxxxxxxxxxxxxxxxx" \
  https://ptt.606.co.il/api/public/v1/rooms

Getting an API key

Sign up or log in to the developers area. The first user to register becomes the super admin and approves new developers. Once approved, generate keys directly from the UI — the raw secret is shown once and cannot be retrieved later.

Endpoints

GET/api/public/v1/healthpublic

Liveness check + database latency.

GET/api/public/v1public

Self-describing endpoint index.

Rooms

GET/roomspublic

List active rooms. Query: ?limit=50&include_inactive=1

POST/roomswrite

Create a new room.

{
  "slug": "team-alpha",
  "name": "Team Alpha",
  "description": "internal channel",
  "max_users": 8
}

GET/rooms/:slugpublic

Room details, event count (24h), and estimated active peers.

PATCH/rooms/:slugwrite

Update room name, description, max_users, or is_active.

DELETE/rooms/:slugadmin

Soft-delete: marks the room inactive.

Events

GET/rooms/:slug/eventspublic

Latest events. Query: ?limit=50&since=ISO&type=talk_start

POST/rooms/:slug/eventspublic

Log an event (used by the web client).

{
  "event_type": "join" | "leave" | "talk_start" | "talk_stop" | "broadcast" | "system",
  "peer_id": "abc123",
  "peer_name": "Alice",
  "payload": { "any": "json" }
}

POST/rooms/:slug/broadcastwrite

Inject a server-side message into the room. Persists an event AND sends a live Realtime broadcast (event: api:broadcast).

{ "message": "Server restart in 5 minutes", "from": "ops" }

API Keys

GET/keysadmin

List keys (raw secrets are never returned).

POST/keysadmin / bootstrap

Create a new API key. Raw secret returned once.

{ "name": "ops-bot", "scopes": ["write","read"] }

DELETE/keys/:idadmin

Revoke a key.

Errors

All errors return JSON of the form:

{ "error": { "code": "invalid_api_key", "message": "...", "details": ... } }

Common codes: missing_api_key, invalid_api_key, insufficient_scope, not_found, validation_failed, slug_taken, room_inactive, db_error, internal_error.

CORS

All endpoints accept cross-origin requests (Access-Control-Allow-Origin: *) and respond to OPTIONS preflights.