Skip to main content
developers/streaming
DeveloperLive streaming

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.

  1. 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.
  2. 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.
  3. Create a key. On the API access card, click Create key, give the key a Name (for example, Production), and confirm your password.
  4. 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 with scheduled_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, never 403.

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

StepCall
Book a streamPOST /v1/streams
List your streamsGET /v1/streams
Read one streamGET /v1/streams/{playback_id}
Start itPOST /v1/streams/{playback_id}/start
Rotate its stream keyPOST /v1/streams/{playback_id}/ingest-key
Get a viewer linkGET /v1/streams/{playback_id}/playback
End itPOST /v1/streams/{playback_id}/end
Read its recordingGET /v1/streams/{playback_id}/recording
Delete its recordingDELETE /v1/streams/{playback_id}/recording
Read the month's usageGET /v1/usage

The stream object

FieldTypeMeaning
playback_idstringThe stream's id. Use it in every other call.
customer_refstringYour reference for who the stream is for.
titlestringThe stream's title.
tierstringstandard_1080p or pro_4k.
statestringscheduled, starting, live, ended or failed.
scheduled_start_attimestampWhen a booking starts itself. Absent when not booked.
started_attimestampWhen billing started. Absent until then.
ended_attimestampWhen the stream ended.
unit_rate_usd_per_hournumberThe rate, fixed when the stream started. Absent before then.
encoder_connectedbooleanWhether we can see your encoder right now.
leg_countintegerHow many redundant transcoders the stream runs on.
legs_readyintegerHow many of them are transcoding right now. Only Read one stream reports it; lists show 0.
recordingobjectThe recording's state, and once the file exists, bytes, duration_seconds and ready_at. See Recordings.
ingestobjectWhat 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"
}
FieldRequiredRules
customer_refYesYour 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.
titleYesUp to 200 characters.
tierYesstandard_1080p or pro_4k.
scheduled_start_atNoBook 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_connected tells you when we can see the encoder. To begin before the booked time, call start.
  • 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 end before 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:

ParameterMeaning
customer_refOnly 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.
statescheduled, starting, live, ended or failed.
recording_stateOnly streams whose recording is in this state. ready finds every recording waiting to be collected.
limit1 to 200. Defaults to 50.
beforeThe 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).

Encoders ask for SRT in one of two shapes:

Encoder asks forValue
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_url in 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 -protocols lists srt).
  • 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 fieldValue
Server (or URL)ingest.server_url (rtmps://…:443/live)
Stream keyingest.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_1080ppro_4k
Resolution1920×10803840×2160
Frame rate3030
Video bitrateabout 6,000 Kbpsabout 16,000 Kbps
Keyframe interval2 seconds2 seconds
AudioAAC, 48 kHz stereoAAC, 48 kHz stereo
Upload speed needed10 Mbps or more25 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.

EncoderVersionSent overSet up asResult
OBS Studio32.2.2, macOSSRTCustom 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 delay1080p, test environment: live, plays; OBS held 30 fps with no dropped frames
OBS Studio32.2.2, macOSSRTAs above at 3840×2160, 16,000 Kbps CBR, with Apple VT H264 Hardware Encoder4K (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 Studio32.2.2, macOSRTMPSCustom service; server_url in Server, stream_key in Stream Key; Stream Delay 2 s with Preserve cutoff point when reconnecting; encoder settings as above1080p, test environment: live, plays; OBS held 30 fps with no dropped frames over 12 minutes
Wirecast16.5.5, macOSSRTDestination 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 stereo1080p, 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
Wirecast16.5.5, macOSRTMPSDestination RTMP Server; its default address (unencrypted RTMP to localhost) replaced with server_url, stream_key in Stream; the same preset1080p, 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 Broadcaster1.5.13, Android 16 emulatorSRTsrt_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 Broadcaster1.5.13, Android 16 emulatorRTMPSserver_url + / + stream_key as one URL; the same video settings1080p, test environment: live 35 s after starting; viewers received 29.58 fps
ffmpeg9.0.2, built with libsrtSRT-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 stereo1080p at 6,000 Kbps, test environment and production; 4K (pro_4k) at 16,000 Kbps, test environment: live, play
ffmpeg9.0.2, Homebrew (TLS by OpenSSL)RTMPS-f flv "<server_url>/<stream_key>"; settings as above1080p, 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 failedSRTRTMPS
One ingest serverOBS back within 3 s; viewers skipped 2.4 s at 1080p and 1.4 s at 4KOBS 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 sOBS 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_yet means 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_deleted or 410 recording_expired means 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"
}
stateMeaning
noneNothing to collect: the stream has not ended, or no video ever arrived.
finalizingThe stream ended and its recording is being closed. Seconds to a couple of minutes.
exportingThe MP4 is being made: about a minute per hour of broadcast, longer for 4K.
readyThe file exists. download_url, bytes and duration_seconds are present.
failedThe file could not be made; failure_code says why.
deletingYou asked us to delete it, and we are.
deletedIt is gone.
expiredThe 30 days passed before it was deleted.
failure_codeMeaning
no_mediaThe recording holds no video that could be exported.
unreadable_mediaThe video could not be made into an MP4.
export_failedThe export failed repeatedly for another reason. Contact support.
  • download_url is 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 supports Range requests for resuming, and HEAD for the size.
  • missing_seconds is how much of the broadcast is not in the file. It is 0 for 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"
    }
  ]
}
  • month is YYYY-MM. Leave it out for the current month so far; ask for a month that has ended to bill from. A malformed month is 400 invalid_month.
  • streams is every stream billed in that month, which is the month it ended, each with your customer_ref, its billable minutes, its rate and what it cost. That is what you bill your own customers from.
  • stream_hour_cap and stream_hours_remaining are null: 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.

StatuserrorMeaning
400invalid_bodyThe body is not valid JSON.
400missing_fieldA required field is missing (title).
400invalid_customer_refcustomer_ref is missing or breaks its rules.
400invalid_titletitle is longer than 200 characters.
400invalid_tiertier is not standard_1080p or pro_4k.
400invalid_statestate is not a stream state.
400invalid_recording_staterecording_state is not a recording state.
400invalid_limitlimit is not a positive whole number.
400invalid_beforebefore is not an RFC 3339 timestamp.
400invalid_monthmonth is not YYYY-MM.
401unauthenticatedThe key is missing, unrecognised or revoked, or your organization's streaming is suspended.
402cap_exceededYour organization's monthly stream-hour cap is spent. Organizations whose keys come from the Hub have no cap.
404not_foundNo such stream for this key.
409already_activeThat customer_ref already has as many streams on air as your account's limit allows (only when a limit is set).
409not_published_yetThe stream is up, but no video has arrived yet.
409stream_not_endedA running stream's recording cannot be deleted.
410recording_deletedYou deleted this stream's recording.
410recording_expiredThe recording passed its 30 days.
500internalSomething failed on our side. Retry.
503unavailableWe could not check your key just now. Retry.
503no_rateNo rate is set for this tier. Contact support.
503playback_unconfiguredViewer 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 becoming ready.
  • 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 /healthz answers 200 {"status": "ok"} while the API is running.
  • GET /readyz answers 200 {"status": "ready"} when the API can take requests, and 503 with not_ready when 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.