The API, for your church’s own tools.

Owners and admins make keys in Dashboard › Integrations › API keys, up to 10 at once. A key is shown once, as it is made: we keep only a fingerprint of it and its first characters, so a lost key is replaced, never recovered. Revoking one stops it at its next request.

Send the key in every request’s Authorization header:

curl https://voclyn.com/api/v1/rooms \
  -H "Authorization: Bearer $VOCLYN_KEY"

Every answer is JSON and never cached. Times are ISO 8601 in UTC; languages are the codes of your per-language links (es, ko, zh-Hant). Lists come as { "data": [ … ] }. When something goes wrong, the status says what kind and the body says why, for programs and for people:

{ "error": { "code": "not_live", "message": "Worship needs a service running in this room, and none is." } }

The API answers browsers from any site (CORS), because a key never travels in a cookie. That is also why a full key must stay on a server: anyone who can read a page’s code can read a key in it.

GET /rooms lists the church’s rooms, the main one first; GET /rooms/{room} reads one. A room is named by its id or by its link word (grace in voclyn.com/grace). Each comes with its live state:

{
  "id": "4f1c2a9e-8b3d-4e62-9a71-0c5d6e7f8a9b",
  "name": "Sanctuary",
  "slug": "grace",
  "main": true,
  "link": "https://voclyn.com/grace",
  "screen_link": "https://voclyn.com/grace/screen",
  "status": "paused",
  "reason": "worship",
  "desk_open": true,
  "service_id": "9b2e5c1a-3d4f-4a6b-8c7d-1e2f3a4b5c6d",
  "spoken_languages": ["en"],
  "languages": ["es", "zh-Hant"],
  "voice_languages": ["es", "zh-Hant"],
  "last_live_at": "2026-11-01T17:02:11.004Z"
}

• status: idle, starting (the sound desk page was asked to go live), live, paused, or ended for a while after a service, until the room turns idle again.
• reason: while paused, worship, private or break.
• desk_open: a sound desk page is open for the room, so Go live can work.
• languages and voice_languages: the church’s own languages for the room, as its plan offers them, and those of them the AI voice reads (each that has a voice).

POST /rooms/{room}/{button} presses one of the sound desk’s buttons and answers with the room as it is after. A booth key is enough. Buttons are POST only, so a link preview can never press one.

curl -X POST https://voclyn.com/api/v1/rooms/grace/worship \
  -H "Authorization: Bearer $VOCLYN_KEY"

Go live answers 202 with status: starting, then the room turns live within seconds; with no sound desk page open it answers 409 desk_closed. The others answer 409 not_live when no service is running. resume, music, pause and stop are taken for speech, worship, break and end.

GET /services lists past and running services, newest first, and needs a full key. room narrows it to one room, limit sets the page (1 to 100, 20 by default), and before pages back: pass the next_before of the last page while has_more is true. GET /services/{id} reads one, with whether its transcript is saved.

{
  "id": "9b2e5c1a-3d4f-4a6b-8c7d-1e2f3a4b5c6d",
  "room": { "id": "4f1c2a9e-8b3d-4e62-9a71-0c5d6e7f8a9b", "name": "Sanctuary", "slug": "grace" },
  "status": "ended",
  "started_at": "2026-11-01T17:02:11.004Z",
  "ended_at": "2026-11-01T18:14:40.498Z",
  "duration_seconds": 4349,
  "peak_listeners": 38,
  "listener_minutes": 2410,
  "spoken_languages": ["en"],
  "languages": ["es", "zh-Hant"],
  "voice_languages": ["es", "zh-Hant"],
  "listeners_by_language": { "es": { "peak": 24 }, "zh-Hant": { "peak": 14 } },
  "sentences": 612,
  "transcript": true
}

GET /services/{id}/transcript returns a saved transcript, if the room saves them. Add lang for one listener language and format for json (the default), txt or srt subtitles. In JSON, text is null for a line nobody was reading in that language at the time; text and SRT show the words as spoken there.

{
  "service_id": "9b2e5c1a-3d4f-4a6b-8c7d-1e2f3a4b5c6d",
  "language": "es",
  "lines": [
    {
      "seq": 1,
      "start_ms": 0,
      "end_ms": 4200,
      "speaker": "1",
      "spoken_language": "en",
      "original": "Good morning, church.",
      "text": "Buenos días, iglesia."
    }
  ]
}

curl "https://voclyn.com/api/v1/services/9b2e5c1a-3d4f-4a6b-8c7d-1e2f3a4b5c6d/transcript?lang=es&format=srt" \
  -H "Authorization: Bearer $VOCLYN_KEY" -o sermon-es.srt

Transcripts are kept for the plan’s period: 90 days on Chapel and 12 months on Church and Campus. A private moment is never saved.

GET /church names the church the key belongs to, its time zone, its plan today, and whether the key is a booth or a full key. GET /api/v1 needs no key and says where these pages are.

Version 1 keeps its paths and fields. New fields and new buttons may appear in it, so read the fields you need and ignore the rest; anything that would break a working tool comes as version 2, announced in advance. Webhooks are described in their own page.