Streaming API
Book, run and bill live streams from your own software. For businesses that offer live streaming to their own customers, and for churches that want to automate their services.
Base URL: https://api.streaming.1stflock.com
On this page
Get an API key
API keys are issued from the Hub, to your organization. Every stream made with one of your keys is billed to your organization.
- Sign up for 1st Flock and choose Streaming. Streaming can be the only thing you choose. It is billed to a card each month, so sign up with a card; nothing is charged until a stream runs.
- Open Streaming in the Hub. If you chose Streaming at sign-up, it is already on. If you are already a 1st Flock customer, open Streaming and click Enable streaming on the Live streaming card; you need a card on file first.
- Create a key. On the API access card, click Create key, give the key a Name (for example,
Production), and confirm your password. - Copy the key. It is shown once, under Your new API key. Store it with your server's other secrets. If it is ever lost or exposed, revoke it on the API access card and create another.
Only an administrator, or someone who has been given the streaming.manage permission, can create or revoke keys. You can create up to 10 keys an hour.
Revoking a key refuses every request made with it from then on. It does not disconnect an encoder that is already broadcasting, because encoders use each stream's own stream key (see Setting up an encoder). Turning streaming off in the Hub, or an unpaid streaming bill, suspends every key your organization holds and disconnects its encoders; streaming and the keys come back when it is turned on again or the bill is paid.
Pricing and billing
Streaming is pay as you go. There is no monthly fee, and no blocks or bundles of hours. Each stream is priced per stream-hour by its quality (tier):
- 1080p streamFull HD. The right choice for nearly every service.
- 4K streamUltra HD, for a 4K camera and an internet connection that can carry it.
- Per minute. A stream is billed for every minute it runs, rounded up to the next whole minute, with a five-minute minimum per stream.
- When the clock starts. For a stream you start with
start, when its video first reaches us. For a booking made withscheduled_start_at, at the booked time, whether or not your encoder has connected, because the capacity is held for you from then. - When it stops. When the stream ends: when you call
end, or when it is ended for you (see Create a stream). - The rate is fixed when the stream starts, and returned on the stream as
unit_rate_usd_per_hour. A price change never applies to a stream that is already running. - Monthly, in arrears. Every stream made with your keys goes on your organization's monthly streaming invoice in the Hub, at the same per-hour rates as streams run from the Hub itself. It is billed on the 1st of the month, for the month just ended, to your card on file. A stream counts toward the month in which it ended (months run midnight to midnight UTC).
- No charge per viewer. Viewers are never charged, and you are not charged for how many there are.
Reselling
If you offer streaming to your own customers, you set your own prices for them. Give every stream the reference you use for that customer, in customer_ref, and read GET /v1/usage after the month ends: it lists every stream billed in that month with its customer_ref, billable minutes and cost. The same breakdown is on the Streaming page in the Hub. Your monthly streaming invoice in the Hub is the bill of record.
Authentication
Base URL:
https://api.streaming.1stflock.com
HTTPS only. Every request carries your API key as a bearer token:
Authorization: Bearer strm_...
A key identifies your organization, and that is who a stream is billed to. Keep keys on your servers: never put one in a web page, a mobile app or anything else a customer can download.
- A missing, unrecognised or revoked key is
401 unauthenticated. So is a valid key while your organization's streaming is suspended. The response is the same in every case, on purpose. If a key that worked yesterday is refused today and you have not revoked it, check the Streaming page in the Hub. - A stream that belongs to another organization is
404 not_found, never403.
Rate limits
Requests are rate limited per client IP address. Poll a stream no more often than every few seconds, and when a request fails, wait before you retry.
Retries and idempotency
start, end and recording deletion are safe to repeat. Rotating a stream key is not: every call issues a new key and retires the last one. To make POST /v1/streams safe to retry, send an Idempotency-Key header with a value you generate, such as a UUID:
Idempotency-Key: 9f2c1b7a-5d0e-4c55-a3f1-2b8d6c1e7f40
A repeat with the same key returns the stream the first request created instead of creating a second one. The repeat does not include the stream key (it is stored only as a hash), so if you lost the first response, rotate the stream key. Idempotency keys are scoped to your organization.
5xx responses are safe to retry (for POST /v1/streams, when you sent an Idempotency-Key).
Quick start
In the examples, values in angle brackets, such as <number>, stand for values that depend on the stream and your rates.
# 1. Book a stream (with no start time, you start it yourself)
curl -s https://api.streaming.1stflock.com/v1/streams \
-H "Authorization: Bearer $STREAMING_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"customer_ref": "grace-chapel", "title": "Sunday Service", "tier": "standard_1080p"}'
# 2. Start it (publishing is refused until you do)
curl -s -X POST https://api.streaming.1stflock.com/v1/streams/<playback_id>/start \
-H "Authorization: Bearer $STREAMING_API_KEY"
# 3. Point the encoder at ingest.srt_url, or ingest.server_url with ingest.stream_key (see "Setting up an encoder")
# 4. Get a link for viewers once media is flowing
curl -s https://api.streaming.1stflock.com/v1/streams/<playback_id>/playback \
-H "Authorization: Bearer $STREAMING_API_KEY"
# 5. End it when the service is over
curl -s -X POST https://api.streaming.1stflock.com/v1/streams/<playback_id>/end \
-H "Authorization: Bearer $STREAMING_API_KEY"
Streams
| Step | Call |
|---|---|
| Book a stream | POST /v1/streams |
| List your streams | GET /v1/streams |
| Read one stream | GET /v1/streams/{playback_id} |
| Start it | POST /v1/streams/{playback_id}/start |
| Rotate its stream key | POST /v1/streams/{playback_id}/ingest-key |
| Get a viewer link | GET /v1/streams/{playback_id}/playback |
| End it | POST /v1/streams/{playback_id}/end |
| Read its recording | GET /v1/streams/{playback_id}/recording |
| Delete its recording | DELETE /v1/streams/{playback_id}/recording |
| Read the month's usage | GET /v1/usage |
The stream object
| Field | Type | Meaning |
|---|---|---|
playback_id | string | The stream's id. Use it in every other call. |
customer_ref | string | Your reference for who the stream is for. |
title | string | The stream's title. |
tier | string | standard_1080p or pro_4k. |
state | string | scheduled, starting, live, ended or failed. |
scheduled_start_at | timestamp | When a booking starts itself. Absent when not booked. |
started_at | timestamp | When billing started. Absent until then. |
ended_at | timestamp | When the stream ended. |
unit_rate_usd_per_hour | number | The rate, fixed when the stream started. Absent before then. |
encoder_connected | boolean | Whether we can see your encoder right now. |
leg_count | integer | How many redundant transcoders the stream runs on. |
legs_ready | integer | How many of them are transcoding right now. Only Read one stream reports it; lists show 0. |
recording | object | The recording's state, and once the file exists, bytes, duration_seconds and ready_at. See Recordings. |
ingest | object | What an encoder needs. See Setting up an encoder. Not included in lists. |
Timestamps are RFC 3339.
Create a stream
POST /v1/streams
Content-Type: application/json
{
"customer_ref": "grace-chapel",
"title": "Sunday Service",
"tier": "standard_1080p",
"scheduled_start_at": "2026-10-04T14:00:00Z"
}
| Field | Required | Rules |
|---|---|---|
customer_ref | Yes | Your reference for the customer. 1 to 128 characters: letters, digits, ., _ and - (not . or .. on its own). We store it and return it; we do not interpret it. |
title | Yes | Up to 200 characters. |
tier | Yes | standard_1080p or pro_4k. |
scheduled_start_at | No | Book the stream for this time. Leave it out to start the stream yourself with start. |
The response is 201 with the stream object, including the one-time stream key:
{
"playback_id": "1846bdac2d8c0ce0e846d4a3817012c9",
"customer_ref": "grace-chapel",
"title": "Sunday Service",
"tier": "standard_1080p",
"state": "scheduled",
"scheduled_start_at": "2026-10-04T14:00:00Z",
"leg_count": <number>,
"legs_ready": 0,
"encoder_connected": false,
"recording": { "state": "none" },
"ingest": {
"key": "strmi_...",
"srt_url": "srt://<ingest host>:8890?streamid=publish:live/1846bdac2d8c0ce0e846d4a3817012c9&passphrase=<passphrase>&pbkeylen=32",
"srt_server": "srt://<ingest host>:8890",
"srt_stream_id": "publish:live/1846bdac2d8c0ce0e846d4a3817012c9",
"srt_passphrase": "<passphrase>",
"server_url": "rtmps://<ingest host>:443/live",
"stream_key": "1846bdac2d8c0ce0e846d4a3817012c9?key=strmi_...",
"endpoints": ["rtmps://<ingest host>:443/live/1846bdac2d8c0ce0e846d4a3817012c9"],
"fanout_required": false
}
}
ingest.key, ingest.srt_url, ingest.srt_passphrase and ingest.stream_key are returned once, when the stream is created, and can never be read again. Store them, or rotate for a new one.
A booking starts itself, and billing starts with it. At scheduled_start_at the stream starts and billing begins, whether or not your encoder is connected, because the capacity is held for you from then.
- Connect early. A booking accepts its encoder from one hour before
scheduled_start_at, so the broadcaster can check the feed. Until the start, nothing is shown to viewers, recorded or billed.encoder_connectedtells you when we can see the encoder. To begin before the booked time, callstart. - No video, no stream. A started stream that receives no video for 15 minutes in a row is ended, whether the encoder never connected or stopped, so a forgotten stream or a closed laptop does not bill all weekend. It is billed until the stream is ended: a stream that never receives any video, booked or started with
start, is billed for those 15 minutes, because the capacity was held from its start. - Cancel for free. Call
endbefore the start time and there is no charge.
You may book and run as many streams for one customer_ref as you like: there is no limit by default on how many are on air at once. If your account has a limit set, starting one more while that many are starting or live is 409 already_active.
List your streams
GET /v1/streams?customer_ref=grace-chapel&state=ended&limit=50
{
"streams": [ { "playback_id": "…", "customer_ref": "grace-chapel", "state": "ended" } ],
"next_before": "2026-09-18T09:14:02.118Z"
}
Newest booking first. All filters are optional:
| Parameter | Meaning |
|---|---|
customer_ref | Only this customer's streams. Use it whenever you show a customer their own streams: filtering a page yourself can miss streams that are on a later page. |
state | scheduled, starting, live, ended or failed. |
recording_state | Only streams whose recording is in this state. ready finds every recording waiting to be collected. |
limit | 1 to 200. Defaults to 50. |
before | The previous page's next_before, to read the next page. |
When next_before is absent you have reached the end. The list is ordered by when each stream was booked, and a booking can be made far ahead, so use recording_state=ready to find recordings rather than reading your whole history.
Read one stream
GET /v1/streams/{playback_id}
Returns the stream object, with an ingest block that has srt_server, srt_stream_id, server_url and endpoints but never the key or the SRT passphrase. It is where to get the push addresses again when setting up another encoder. legs_ready against leg_count shows how many of the stream's redundant transcoders are running.
Start a stream
POST /v1/streams/{playback_id}/start
The stream moves to starting, then to live once video is flowing. Your encoder is refused until you call this (or, for a booking, until an hour before its start), and that refusal looks like a wrong key. Starting a stream that has already started is safe and returns its current state.
Rotate a stream key
POST /v1/streams/{playback_id}/ingest-key
{
"key": "strmi_...",
"srt_url": "srt://<ingest host>:8890?streamid=publish:live/<playback_id>&passphrase=<passphrase>&pbkeylen=32",
"srt_server": "srt://<ingest host>:8890",
"srt_stream_id": "publish:live/<playback_id>",
"srt_passphrase": "<passphrase>",
"server_url": "rtmps://<ingest host>:443/live",
"stream_key": "<playback_id>?key=strmi_...",
"endpoints": ["rtmps://<ingest host>:443/live/<playback_id>"],
"fanout_required": false
}
Note the shape: the ingest block on its own, not wrapped in ingest. The new key replaces the old one immediately, with a new SRT passphrase, and an encoder still using the old key or passphrase is disconnected within seconds and cannot reconnect, so rotate between broadcasts, not during one.
End a stream
POST /v1/streams/{playback_id}/end
Returns the stream object with what the stream cost:
{ "playback_id": "…", "state": "ended", "billed_usd": <number> }
Safe to repeat: a call that timed out can be sent again, and you get the same answer and the same charge.
Setting up an encoder
Every stream takes SRT or RTMPS, to the same edge, and both are encrypted. Use SRT whenever the encoder supports it, and RTMPS only for encoders without SRT. We do not accept unencrypted ingest: plain rtmp://, and SRT without the passphrase, are refused.
SRT resends what a lossy uplink drops, so short bursts of packet loss do not reach the picture. It does not hide a dropped connection: if the encoder's connection to us is cut, viewers lose the seconds the encoder takes to reconnect (see Reconnects).
SRT (recommended)
Encoders ask for SRT in one of two shapes:
| Encoder asks for | Value |
|---|---|
| One address (OBS, ffmpeg, mobile apps) | ingest.srt_url |
| A server, a Stream ID and a passphrase (hardware encoders) | ingest.srt_server, ingest.srt_stream_id and ingest.srt_passphrase, with the key length set to 32 (AES-256) |
- OBS: in Settings → Stream, choose Custom, put the whole
srt_urlin Server, and leave Stream Key empty. Turn Stream Delay off: never use Stream Delay with SRT. - ffmpeg: send MPEG-TS to the
srt_url, quoted, for example-f mpegts "<srt_url>". ffmpeg must be built with SRT support (ffmpeg -protocolslistssrt). - Use caller mode, and leave the latency at the encoder's default.
The Stream ID names the stream (publish:live/<playback_id>) and carries no secret. The passphrase is the credential: the encoder encrypts with it, and a connection without it, or with an old one, is refused.
RTMPS (for encoders without SRT)
Encoders ask for two values:
| Encoder field | Value |
|---|---|
| Server (or URL) | ingest.server_url (rtmps://…:443/live) |
| Stream key | ingest.stream_key |
The stream key is the stream's playback_id with the key attached as ?key=. Putting ingest.key on its own in the stream key field is the common mistake, and it is refused. The server must start with rtmps://: an rtmp:// address is refused. In OBS over RTMPS, also turn on Stream Delay (2 seconds) with Preserve cutoff point when reconnecting, so a dropped connection re-sends what it lost.
Recommended settings:
standard_1080p | pro_4k | |
|---|---|---|
| Resolution | 1920×1080 | 3840×2160 |
| Frame rate | 30 | 30 |
| Video bitrate | about 6,000 Kbps | about 16,000 Kbps |
| Keyframe interval | 2 seconds | 2 seconds |
| Audio | AAC, 48 kHz stereo | AAC, 48 kHz stereo |
| Upload speed needed | 10 Mbps or more | 25 Mbps or more |
Set the keyframe interval to 2 seconds. Video is cut into segments on keyframes, and a longer or automatic interval makes playback stall and start slowly. It also bounds the gap after a reconnect, because a stream can only be picked back up at a keyframe. Set the encoder to reconnect on its own as quickly as it allows.
What we have tested
These are the encoders we have run against our streaming service ourselves, on 31 October 2026, in our test environment and in production. Each ran on a MacBook Pro (Apple M2 Max, macOS 26.6.2) sending a recorded service (Larix ran in the Android emulator on the same Mac and sent the emulator's test camera with silent audio), and each was checked from the viewer's side: the stream went live, and the playback link carried the full set of qualities with the top one at the resolution sent, H.264 video at 30 frames a second and AAC stereo audio at 48 kHz. Frame rates below are what viewers received, counted over a full minute.
| Encoder | Version | Sent over | Set up as | Result |
|---|---|---|---|---|
| OBS Studio | 32.2.2, macOS | SRT | Custom service; srt_url in Server, Stream Key empty; Stream Delay off. x264 CBR 6,000 Kbps, keyframe interval 2 s, preset veryfast, profile high; AAC 160 Kbps, 48 kHz stereo; 1920×1080 at 30 fps; reconnect on, 1 s retry delay | 1080p, test environment: live, plays; OBS held 30 fps with no dropped frames |
| OBS Studio | 32.2.2, macOS | SRT | As above at 3840×2160, 16,000 Kbps CBR, with Apple VT H264 Hardware Encoder | 4K (pro_4k), test environment: live, plays; 1 frame dropped in 3,668, about 4% CPU. With x264 veryfast the same Mac dropped 57% of frames at 4K |
| OBS Studio | 32.2.2, macOS | RTMPS | Custom service; server_url in Server, stream_key in Stream Key; Stream Delay 2 s with Preserve cutoff point when reconnecting; encoder settings as above | 1080p, test environment: live, plays; OBS held 30 fps with no dropped frames over 12 minutes |
| Wirecast | 16.5.5, macOS | SRT | Destination SRT: Secure Reliable Transport; srt_server host in Address, 8890 in Port, srt_passphrase in Passphrase, srt_stream_id in Stream ID (Wirecast has no key-length setting). x264 6,000 Kbps with Strict Constant Bitrate, key frame every 60 frames, 1920×1080 at 30 fps, Wirecast's default quality (Super Fast) and profile (Baseline); AAC 160 Kbps, 48 kHz stereo | 1080p, test environment: live 37 s after starting; viewers received 29.97 fps; Wirecast counted no dropped frames. Run in Wirecast's demo mode, which watermarks the picture |
| Wirecast | 16.5.5, macOS | RTMPS | Destination RTMP Server; its default address (unencrypted RTMP to localhost) replaced with server_url, stream_key in Stream; the same preset | 1080p, test environment: live 41 s after starting; viewers received 29.80 fps; Wirecast counted 28 dropped frames in about 4 minutes. The Output Settings window shows the stream key in clear text |
| Larix Broadcaster | 1.5.13, Android 16 emulator | SRT | srt_url as the connection URL, caller mode, srt_stream_id in streamid, srt_passphrase in Passphrase, key length 32, latency default; camera 1920×1080 at "30 fixed rate", keyframe 2 s, Larix's default 1080p bitrate (3,000 Kbps) | 1080p, test environment: live 33 s after starting; viewers received 29.62 fps. With Larix's default key length of 16 it also connects, encrypted with AES-128 |
| Larix Broadcaster | 1.5.13, Android 16 emulator | RTMPS | server_url + / + stream_key as one URL; the same video settings | 1080p, test environment: live 35 s after starting; viewers received 29.58 fps |
| ffmpeg | 9.0.2, built with libsrt | SRT | -f mpegts "<srt_url>"; libx264 veryfast, high, CBR (-b:v, -minrate, -maxrate and -bufsize equal, nal-hrd=cbr), -g 60 -keyint_min 60 -sc_threshold 0; AAC 160k, 48 kHz stereo | 1080p at 6,000 Kbps, test environment and production; 4K (pro_4k) at 16,000 Kbps, test environment: live, play |
| ffmpeg | 9.0.2, Homebrew (TLS by OpenSSL) | RTMPS | -f flv "<server_url>/<stream_key>"; settings as above | 1080p, test environment and production; 4K, test environment: live, play |
Larix's default key length is 16 (AES-128): the edge accepts the key length the encoder offers, so set it to 32 for AES-256. The free version of Larix overlays a test-stream notice and stops streaming after 60 minutes (Larix Premium removes both), and its connection form can drop characters while you type the URL, so check it after pasting.
We also checked that unencrypted ingest is refused, in production: plain rtmp:// on port 1935, and SRT without the passphrase, never connected, with a real stream key for a started stream.
Known not to work: ffmpeg built with Apple's SecureTransport for TLS (--enable-securetransport) connects over RTMPS and is accepted, then cannot send video, and the connection is closed about 30 seconds later. Use an ffmpeg built with OpenSSL, or send over SRT.
Not yet tested by us: OBS at 4K over RTMPS, OBS on Windows or Linux, Wirecast on Windows or at 4K, Larix on iPhone or on a real Android phone, a server failure while sending from Wirecast or Larix, and every other encoder (vMix, hardware encoders). They take the same values; set them up by their maker's documentation using the fields above, SRT first.
Reconnects
Every stream is transcoded redundantly, so losing a transcoder does not interrupt viewers. The encoder's own connection is not redundant: it reaches one ingest server at a time. If that connection is cut, by the encoder's network or by the server it is sending to, the encoder has to reconnect, and viewers skip past what the encoder sent while the connection broke. Set the encoder to reconnect on its own, as quickly as it allows.
What we measured on 31 October 2026, with OBS Studio 32.2.2 on macOS in our test environment, shutting down the ingest server OBS was sending to mid-stream (or that server and one other) and reading what viewers received frame by frame. OBS used the settings in the table above: over SRT, Stream Delay off; over RTMPS, Stream Delay 2 s with preserve.
| What failed | SRT | RTMPS |
|---|---|---|
| One ingest server | OBS back within 3 s; viewers skipped 2.4 s at 1080p and 1.4 s at 4K | OBS back within about 3 s (once 17 s); viewers skipped 1.0 to 2.0 s over three runs |
| Two at once (rare) | OBS back in 7 s; viewers skipped 7.9 s | OBS back in 3 s; viewers skipped 1.6 s |
Two at once ran once over each. An earlier run over SRT, on 11 October 2026, skipped between 2 and 12 s in that case.
In every run the picture did not freeze and playback did not pause: viewers watch about a minute behind live, which covered the longest gap. Over RTMPS, each reconnect adds its length to OBS's Stream Delay, so the stream drifts that much further behind live. Each case ran one to three times: treat the numbers as a guide, not a promise. A failure on our side is something viewers can notice.
endpoints lists the push addresses for the stream. When fanout_required is true there is more than one, and an encoder that publishes the same feed to all of them is protected against losing the server that receives its feed.
Playback
GET /v1/streams/{playback_id}/playback
{
"playback_url": "<HLS master playlist URL>",
"expires_at": "2026-10-04T20:26:01Z"
}
playback_url is an HLS playlist that plays in any HLS player: Safari and iOS play it natively, other browsers with a JavaScript HLS player, and Android, smart TVs and streaming boxes through their own HLS support. Nothing else needs fetching; the link carries its own access to everything beneath it.
- The link is a credential. Request it on your server, per viewer or per page load, rather than publishing a long-lived one. It expires at
expires_at; request a new one when it does. 409 not_published_yetmeans the stream is up but no video has arrived yet. Poll until you get a link rather than handing a viewer one that will not play.410 recording_deletedor410 recording_expiredmeans the recording is gone, so there is nothing left to play.
Expect viewers to be about a minute behind the camera. Playback starts that far back on purpose: if something fails between the encoder and the viewer, viewers have that minute to keep watching while it recovers (Reconnects has what we have measured). If the encoder's own connection drops and comes back, the seconds it was disconnected are skipped (see Reconnects). That suits a service, a lecture or an event; it is not suited to a two-way conversation with the audience.
Viewers are not charged, and you are not charged per viewer.
Recordings
Every stream is recorded. When it ends, we produce one MP4 file: the top quality you broadcast in, with its audio, exactly the picture viewers saw.
We keep a recording for 30 days, and then it is deleted. Copy it somewhere you control within that time, then delete ours.
Read a recording
GET /v1/streams/{playback_id}/recording
{
"playback_id": "1846bdac2d8c0ce0e846d4a3817012c9",
"state": "ready",
"bytes": 2893012004,
"duration_seconds": 5412.48,
"missing_seconds": 0,
"ready_at": "2026-10-04T15:41:07Z",
"retained_until": "2026-11-03T15:41:07Z",
"download_url": "<MP4 download URL>",
"expires_at": "2026-10-04T16:43:12Z"
}
state | Meaning |
|---|---|
none | Nothing to collect: the stream has not ended, or no video ever arrived. |
finalizing | The stream ended and its recording is being closed. Seconds to a couple of minutes. |
exporting | The MP4 is being made: about a minute per hour of broadcast, longer for 4K. |
ready | The file exists. download_url, bytes and duration_seconds are present. |
failed | The file could not be made; failure_code says why. |
deleting | You asked us to delete it, and we are. |
deleted | It is gone. |
expired | The 30 days passed before it was deleted. |
failure_code | Meaning |
|---|---|
no_media | The recording holds no video that could be exported. |
unreadable_media | The video could not be made into an MP4. |
export_failed | The export failed repeatedly for another reason. Contact support. |
download_urlis a credential, and it lasts an hour. Request a fresh one whenever you start or resume a download; a transfer already under way when it expires completes. It supportsRangerequests for resuming, andHEADfor the size.missing_secondsis how much of the broadcast is not in the file. It is0for a complete recording. Check it before you delete ours.- If the encoder dropped during the service, the file keeps the real timeline, holding the last picture for as long as the connection was down.
- Poll this endpoint, or list
GET /v1/streams?recording_state=ready, to find recordings to collect.
Delete a recording
DELETE /v1/streams/{playback_id}/recording
Deletes the MP4 and everything else recorded for the stream. It cannot be undone: the recording can no longer be downloaded or played, and the playback endpoint answers 410 recording_deleted. A viewer who already holds a playback link may still be served parts of the broadcast until that link expires.
202 with state deleting means the deletion is under way (usually done within a minute); 200 with deleted means nothing is left. Calling it again is safe. You can delete a recording at any time after the stream ends, even before the MP4 is ready; while the stream is running the answer is 409 stream_not_ended.
Usage
GET /v1/usage?month=2026-09
{
"month": "2026-09",
"stream_hours_used": <number>,
"stream_hour_cap": null,
"stream_hours_remaining": null,
"streams": [
{
"playback_id": "1846bdac2d8c0ce0e846d4a3817012c9",
"customer_ref": "grace-chapel",
"title": "Sunday Service",
"tier": "pro_4k",
"billable_minutes": 92,
"unit_rate_usd_per_hour": <number>,
"amount_usd": <number>,
"occurred_at": "2026-09-14T15:32:11Z"
}
]
}
monthisYYYY-MM. Leave it out for the current month so far; ask for a month that has ended to bill from. A malformed month is400 invalid_month.streamsis every stream billed in that month, which is the month it ended, each with yourcustomer_ref, its billable minutes, its rate and what it cost. That is what you bill your own customers from.stream_hour_capandstream_hours_remainingarenull: an organization whose keys come from the Hub has no monthly cap.
Errors
Every error is JSON:
{ "error": "invalid_tier", "detail": "tier must be standard_1080p or pro_4k" }
detail is for people and may change; branch on error.
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_body | The body is not valid JSON. |
| 400 | missing_field | A required field is missing (title). |
| 400 | invalid_customer_ref | customer_ref is missing or breaks its rules. |
| 400 | invalid_title | title is longer than 200 characters. |
| 400 | invalid_tier | tier is not standard_1080p or pro_4k. |
| 400 | invalid_state | state is not a stream state. |
| 400 | invalid_recording_state | recording_state is not a recording state. |
| 400 | invalid_limit | limit is not a positive whole number. |
| 400 | invalid_before | before is not an RFC 3339 timestamp. |
| 400 | invalid_month | month is not YYYY-MM. |
| 401 | unauthenticated | The key is missing, unrecognised or revoked, or your organization's streaming is suspended. |
| 402 | cap_exceeded | Your organization's monthly stream-hour cap is spent. Organizations whose keys come from the Hub have no cap. |
| 404 | not_found | No such stream for this key. |
| 409 | already_active | That customer_ref already has as many streams on air as your account's limit allows (only when a limit is set). |
| 409 | not_published_yet | The stream is up, but no video has arrived yet. |
| 409 | stream_not_ended | A running stream's recording cannot be deleted. |
| 410 | recording_deleted | You deleted this stream's recording. |
| 410 | recording_expired | The recording passed its 30 days. |
| 500 | internal | Something failed on our side. Retry. |
| 503 | unavailable | We could not check your key just now. Retry. |
| 503 | no_rate | No rate is set for this tier. Contact support. |
| 503 | playback_unconfigured | Viewer and download links are not available right now. Retry later. |
Limits
- No webhooks. Poll
GET /v1/streams/{playback_id}for state changes, including a recording becomingready. - No limit by default on streams on air per
customer_ref. Bookings are unlimited too. - Recordings are kept for 30 days.
- Viewers are about a minute behind live. Not suited to two-way conversation.
Service status
Two endpoints need no key and are safe to point a monitor at:
GET /healthzanswers200 {"status": "ok"}while the API is running.GET /readyzanswers200 {"status": "ready"}when the API can take requests, and503withnot_readywhen it cannot. Use this one for "can I book and start streams right now".
Neither says anything about a particular stream. For that, read the stream.
Browser console
If you would rather not write code for every task, the console does the same things through the same API:
https://api.streaming.1stflock.com/console/
Sign in with an API key to book a stream, read its stream key once, start it, get a viewer link, end it, and see the month's cost broken down by customer_ref. The key is held only in that browser tab and is gone when you close it.