Skip to content

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) and limit (default 20; values above 50 are clamped) and return data, page, limit and total.
  • Every response carries a Glossa-Request-Id header and Cache-Control: no-store.
  • GET /v1 needs no key and returns the links to this reference and the OpenAPI document.

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

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

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

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

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"
}

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

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 }
]
}

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.

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

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

GET /v1/recaps/{id}, scope recaps:read. One recap with the same fields as a list entry.

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
}

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.

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.

Still stuck?Chat with us, submit a ticket, or write to info@glossa.live. Most questions get an answer within the day.
Chat with usSubmit a ticket