API reference
Base URL https://api.glossa.live/v1. Every request carries Authorization: Bearer glk_live_…; the REST API page explains keys and scopes. The same information is published as an OpenAPI 3.1 document for Swagger UI, Postman, code generators and AI agents.
Conventions that hold everywhere:
- Responses are JSON with snake_case fields. Timestamps are UTC in ISO 8601; days are
YYYY-MM-DD; ids are UUIDs. - Lists take
page(from 1) andlimit(default 20; values above 50 are clamped) and returndata,page,limitandtotal. - Every response carries a
Glossa-Request-Idheader andCache-Control: no-store. GET /v1needs no key and returns the links to this reference and the OpenAPI document.
Account endpoints
Section titled “Account endpoints”GET /v1/me, any scope. The church this key belongs to, its plan and hours, the pay-as-you-go balance, and the scopes of the key in use.
{ "church": { "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "name": "Grace Church", "slug": "grace-church", "page_url": "https://glossa.live/grace-church" }, "plan": { "type": "subscription", "name": "Standard", "billing_interval": "month", "period_start": "2026-10-13T00:00:00.000Z", "period_end": "2026-11-13T00:00:00.000Z", "hours_included": 25, "hours_used": 3.5, "hours_remaining": 21.5 }, "balance_usd": null, "key": { "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "scopes": ["services:read", "sessions:read", "usage:read", "recaps:read"] }}| Field | Meaning |
|---|---|
church.slug, church.page_url |
The church page (glossa.live/<slug>); null until a slug is set |
plan.type |
payg, subscription or trial (a subscription in its trial period) |
plan.hours_included, hours_used, hours_remaining |
Language-hours of the current period; subscriptions only, null on pay-as-you-go |
balance_usd |
Pay-as-you-go ledger balance; null on a subscription. The account balance, not a live estimate of unbilled usage |
key.scopes |
What this key may read |
Service endpoints
Section titled “Service endpoints”List services
Section titled “List services”GET /v1/services, scope services:read. Your church’s services (translation rooms), newest scheduled date first. Deleted services are not included.
| Parameter | In | Type | Description |
|---|---|---|---|
page |
query | integer | 1-based page number, default 1 |
limit |
query | integer | Items per page, default 20, at most 50 |
{ "data": [ { "id": "3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "title": "Sunday Service", "speaker_language": "en-US", "limited_languages": ["es-ES", "pt-BR"], "date": "2026-10-25", "time": "10:00", "recurring": true, "private": false, "is_live": false, "urls": { "listener": "https://glossa.live/grace-church/3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "embed": "https://glossa.live/embed/3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "iframe": "https://glossa.live/iframe/3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c" } } ], "page": 1, "limit": 20, "total": 1}| Field | Meaning |
|---|---|
speaker_language |
The language the speaker uses, or multi |
limited_languages |
Listener languages this service is limited to; empty means every language is available |
date, time |
The scheduled date and time, null when not set |
private |
Private services are hidden from the church page |
is_live |
The stored live flag; use Service status for the authoritative state and listeners |
urls.listener |
The page listeners open, the QR code target |
urls.embed |
The captions-only overlay for OBS, vMix or ProPresenter; always pass ?lang= (see Embed and iframe parameters) |
urls.iframe |
The full listener experience for embedding in your own site |
One service
Section titled “One service”GET /v1/services/{id}, scope services:read. One service with two fields the list does not carry.
{ "id": "3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "title": "Sunday Service", "speaker_language": "en-US", "limited_languages": ["es-ES", "pt-BR"], "date": "2026-10-25", "time": "10:00", "recurring": true, "private": false, "is_live": false, "urls": { "listener": "https://glossa.live/grace-church/3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "embed": "https://glossa.live/embed/3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "iframe": "https://glossa.live/iframe/3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c" }, "max_session_minutes": 240, "webhook": { "enabled": false }}| Field | Meaning |
|---|---|
max_session_minutes |
Browser-microphone sessions stop after this many minutes; RTMP sessions have no cap; null when unlimited |
webhook.enabled |
Whether the per-sentence translation webhook is on for this service |
Service status
Section titled “Service status”GET /v1/services/{id}/status, scope services:read. Whether the service is live right now, its audio source, when the session started and how many people listen in each language. Poll every 5 seconds or slower.
{ "service_id": "3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "live": true, "basis": "memory", "source": "rtmp", "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "started_at": "2026-10-25T10:02:14.000Z", "duration_seconds": 1745, "listeners": { "total": 38, "by_language": [ { "code": "es-ES", "count": 31 }, { "code": "pt-BR", "count": 7 } ] }, "as_of": "2026-10-25T10:31:19.000Z"}| Field | Meaning |
|---|---|
live |
Whether a session is running |
basis |
memory: the live state of the server running the session. database: only the stored flag said the service is live; listeners are unknown |
source |
microphone, rtmp, srt or url while live, otherwise null |
session_id |
Use with One session after the session ends |
started_at, duration_seconds |
The running session; null when not live |
listeners.total, listeners.by_language |
People listening right now; caption overlays count too |
as_of |
When this snapshot was taken |
Stream key
Section titled “Stream key”GET /v1/services/{id}/stream-key, scope stream_keys:read. For hands-free sessions: point an RTMP encoder at rtmp_url with stream_key. The session starts when the encoder connects and ends when it disconnects; see RTMP ingest and stream keys. Treat the key as a secret.
| Parameter | In | Type | Description |
|---|---|---|---|
language |
query | string | Speech language baked into the key, for example es-ES or multi; defaults to the service’s speaker language |
{ "rtmp_url": "rtmp://stream.glossa.live:1935/live", "stream_key": "glossa_M2YyYjdjMWUt…", "language": "en-US"}Session endpoints
Section titled “Session endpoints”Sessions of a service
Section titled “Sessions of a service”GET /v1/services/{id}/sessions, scope sessions:read. Past and running sessions, newest first. billable_minutes and cost_usd appear once a session has ended and its usage is computed, usually within minutes.
| Parameter | In | Type | Description |
|---|---|---|---|
page |
query | integer | 1-based page number, default 1 |
limit |
query | integer | Items per page, default 20, at most 50 |
from |
query | string | ISO 8601, inclusive lower bound on started_at |
to |
query | string | ISO 8601, exclusive upper bound on started_at |
{ "data": [ { "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "service_id": "3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "service_title": "Sunday Service", "started_at": "2026-10-25T10:02:14.000Z", "ended_at": "2026-10-25T11:31:40.000Z", "duration_seconds": 5366, "status": "ended", "speaker_language": "en-US", "source": "rtmp", "peak_listeners": 41, "unique_listeners": 57, "languages": ["es-ES", "pt-BR"], "billable_minutes": 62, "cost_usd": 5.17, "end_reason": null } ], "page": 1, "limit": 20, "total": 1}| Field | Meaning |
|---|---|
status |
live or ended |
source |
microphone, rtmp, srt or url |
peak_listeners, unique_listeners |
The most people listening at once, and how many different people listened |
languages |
Languages at least one listener used |
billable_minutes |
Null while the session is live or its usage is still being computed |
cost_usd |
Pay-as-you-go cost; null on a subscription or while pending |
end_reason |
Why the session ended, when recorded, for example time_limit |
One session
Section titled “One session”GET /v1/sessions/{id}, scope sessions:read. The same fields as a list entry plus languages_detail: per language, the minutes translated and the people who listened.
{ "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "service_id": "3f2b7c1e-9d4a-4b8e-a1c2-0d5e6f7a8b9c", "service_title": "Sunday Service", "started_at": "2026-10-25T10:02:14.000Z", "ended_at": "2026-10-25T11:31:40.000Z", "duration_seconds": 5366, "status": "ended", "speaker_language": "en-US", "source": "rtmp", "peak_listeners": 41, "unique_listeners": 57, "languages": ["es-ES", "pt-BR"], "billable_minutes": 62, "cost_usd": 5.17, "end_reason": null, "languages_detail": [ { "code": "es-ES", "minutes": 62, "listeners": 48 }, { "code": "pt-BR", "minutes": 40, "listeners": 9 } ]}Transcript
Section titled “Transcript”GET /v1/sessions/{id}/transcript, scope sessions:read. Every utterance with its translations. A language only has text for the minutes someone listened in it.
| Parameter | In | Type | Description |
|---|---|---|---|
format |
query | string | json (default), txt or srt; the last two return text/plain |
language |
query | string | Return this translation, for example es-ES; omit for the original |
{ "session_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "lines": [ { "at": "2026-10-25T10:02:19.000Z", "original": "Good morning, everyone.", "translations": { "es-ES": "Buenos días a todos.", "pt-BR": "Bom dia a todos." } }, { "at": "2026-10-25T10:02:24.500Z", "original": "Please open your Bibles to Mark 4.", "translations": { "es-ES": "Por favor abran sus Biblias en Marcos 4." } } ], "truncated": false}truncated is true when the session hit the transcript row cap and lines are missing at the end. With format=srt the lines become numbered subtitles timed from the start of the session; with format=txt one line per utterance.
Usage endpoint
Section titled “Usage endpoint”GET /v1/usage, scope usage:read. Minutes of spoken content that were transcribed or translated, with the pay-as-you-go cost (null on a subscription). Silence and songs are not billed.
| Parameter | In | Type | Description |
|---|---|---|---|
from |
query | string | First day, YYYY-MM-DD, inclusive; default the first day of the current month (UTC) |
to |
query | string | Last day, inclusive; default the last day of the current month (UTC). Ranges up to 366 days |
group_by |
query | string | day (default), language or service |
group_by=service is computed from the sessions in range and refuses ranges with more than 500 sessions; narrow the dates in that case.
{ "from": "2026-10-01", "to": "2026-10-31", "group_by": "language", "rows": [ { "key": "es-ES", "minutes": 248, "cost_usd": 20.67 }, { "key": "pt-BR", "minutes": 160, "cost_usd": 13.33 } ], "totals": { "minutes": 408, "cost_usd": 34 }, "plan": null}| Field | Meaning |
|---|---|
rows[].key |
The day (YYYY-MM-DD), the language code or the service id, depending on group_by |
rows[].minutes, totals.minutes |
Billed minutes |
rows[].cost_usd, totals.cost_usd |
Pay-as-you-go cost; null on a subscription |
plan |
The current subscription period: hours_included, hours_used, hours_remaining; null on pay-as-you-go |
Weekly recap endpoints
Section titled “Weekly recap endpoints”Weekly recaps
Section titled “Weekly recaps”GET /v1/recaps, scope recaps:read. Your recaps, one per service and language, most recent service first: title, big idea, quote, caption, scripture references, stats and the generated files.
| Parameter | In | Type | Description |
|---|---|---|---|
limit |
query | integer | How many recaps, default and maximum 52 |
{ "data": [ { "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "weekend": "2026-10-25", "language": "en", "title": "Hope in the Storm", "big_idea": "God is present in trouble.", "quote": "Peace, be still.", "caption": "This Sunday we looked at Mark 4 and what it means to trust in the storm.", "hashtags": ["#faith", "#hope"], "scripture_refs": ["Mark 4:35-41"], "stats": { "listeners": 42, "languages": 3, "minutesLive": 88, "phrasesTranslated": 1240 }, "files": [ { "key": "quote-square.jpg", "url": "/v1/recaps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/files/quote-square.jpg" }, { "key": "study-guide.pdf", "url": "/v1/recaps/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/files/study-guide.pdf" } ], "email_sent_at": "2026-10-26T12:00:00.000Z", "created_at": "2026-10-26T11:00:00.000Z" } ]}| Field | Meaning |
|---|---|
weekend |
The local date of the recapped service. One date can have several recaps, so identify a recap by its id |
language |
The language the recap is written in |
caption |
A ready-to-post social caption; hashtags go with it |
stats |
listeners, languages, minutesLive, phrasesTranslated, and a byLanguage breakdown when available |
files[] |
The generated materials; fetch each url (relative to https://api.glossa.live) for a signed download link, see Recap file |
email_sent_at |
When the recap email went out; null if it was not sent |
One recap
Section titled “One recap”GET /v1/recaps/{id}, scope recaps:read. One recap with the same fields as a list entry.
Recap file
Section titled “Recap file”GET /v1/recaps/{id}/files/{key}, scope recaps:read. A download link for one generated file, valid for 600 seconds. Add ?redirect=1 to be redirected (302) to the file instead of receiving the link.
| Parameter | In | Type | Description |
|---|---|---|---|
key |
path | string | quote-square.jpg, quote-story.jpg, verse-square.jpg, study-guide.pdf or kids-page.pdf |
redirect |
query | string | 1 to redirect to the file |
{ "url": "https://…/storage/v1/object/sign/weekly-recaps/…", "expires_in": 600}Errors
Section titled “Errors”Every error has the same shape; details is present on 400 responses and lists what was wrong with the parameters.
{ "error": { "code": "invalid_request", "message": "Invalid query parameters", "request_id": "9b1c2d3e-…", "details": [{ "path": ["limit"], "message": "Expected number" }] }}| Status | code |
When |
|---|---|---|
| 400 | invalid_request |
A parameter is malformed |
| 401 | unauthenticated |
Missing, unknown, revoked or expired key |
| 403 | insufficient_scope |
The key lacks the scope the endpoint needs |
| 404 | not_found |
No such resource for your church, including services you deleted |
| 429 | rate_limited |
Too many requests |
| 500 | internal |
Something failed on our side |
request_id matches the Glossa-Request-Id response header. Quote it when you write to info@glossa.live.
Rate limits
Section titled “Rate limits”Each key may make 300 requests per minute, and each IP address 600 requests per minute across all endpoints and keys (requests with a missing or wrong key count too). The two endpoints that need no key, GET /v1 and GET /v1/openapi.json, have only the IP limit. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets); a 429 also carries Retry-After.