ShowBits automations
n8n, Zapier, Make and similar tools reach a workspace with a connection's key: they read its clips and episodes, approve clips in review or send them back, and hear about events through webhooks. In every plan; the REST API (Enterprise and OnPremise) is not needed.
Base address https://app.showbits.ai/api/automation/v1 · OpenAPI 3.1 · REST API
The key
Admins and owners create a connection in ShowBits under Integrations → n8n, Zapier & Make and get its key once. Every request carries it: Authorization: Bearer sbau_…. It opens only these routes, only in its workspace. Whatever it does, it does in the name of the person who answers for the connection; if that person leaves or is no longer an admin, requests get 403 owner until someone takes the connection over.
Approving
A clip in review waits for one step of the workspace's approval (approval.stage of approval.stages). POST …/approve and …/reject name that step in stage: if the clip has moved on (a repeated event, a second click), nothing happens and the answer is 409 stale with where the clip is now. by is who clicked, as your tool knows them; the audit log keeps it as reported.
Embargo
A connection sees clips and episodes under embargo only if it was made to. Otherwise lists leave them out and a clip or episode answers 409 embargo with embargoUntil, until the embargo ends: then episode.embargo_ended arrives.
Errors
Errors come as JSON {"error": "…"} with a fixed word: 401 unauthorized, 403 inactive or owner, 404 notFound, 409 stale or embargo, 422 invalid or target, 429 tooMany or limit.
Limits
300 requests a minute per connection, failed ones included; beyond that 429 with Retry-After. Links to files (video, pictures, WebVTT) are signed and last an hour: fetch them when you need them.
Versions
/v1 only changes by adding: new fields, routes and events. Please ignore unknown fields in answers; unknown fields in requests are refused.
In n8n
- Credentials → Add credential → Header Auth: name
Authorization, valueBearer, a space and the key. - An HTTP Request node with this credential:
GET https://app.showbits.ai/api/automation/v1/meanswers with the connection and its workspace. - A Webhook node (POST) for the events: copy its production URL into the connection's webhooks in ShowBits, or let the workflow subscribe with
POST …/hooks. Self-hosted n8n needs an https address reachable from the internet. - Check the signature with the Crypto node (HMAC-SHA256 of
t.body, raw body) and drop repeats by the event'sid(Remove Duplicates).
Zapier and Make: the same with their HTTP modules (Webhooks by Zapier, Make's HTTP app): the header Authorization on each request, a webhook address for the events.
Webhooks
Each event arrives as a POST with ShowBits-Event, ShowBits-Delivery and ShowBits-Signature: t=…,v1=… (HMAC-SHA256 of t.body with the webhook's secret), retried for over a day when your address does not answer with 2xx. Events name the clip or episode by id only (object); fetch the rest from the routes. via is automation for what a connection did.
A connection may subscribe to these events:
clip.approvedclip.deletedclip.forwardedclip.rejectedclip.submittedclip.video_readyepisode.analysedepisode.createdepisode.deletedepisode.embargo_changedepisode.embargo_endedepisode.submitted
import { createHmac, timingSafeEqual } from "node:crypto";
// header: the ShowBits-Signature header; body: the raw request body; secret: whsec_…
export function verify(header, body, secret, toleranceSec = 300) {
const parts = header.split(",").map((p) => p.trim().split("="));
const t = Number(parts.find(([k]) => k === "t")?.[1]);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
return parts.some(([k, v]) => k === "v1" && v?.length === 64 && timingSafeEqual(Buffer.from(v, "hex"), expected));
}Routes
Connection
get/meThe connection, its workspace and limits
With the connection's key
200The connection ·Connection401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Clips
get/clipsThe workspace's clips, oldest first, by status and episode
Clips of episodes under embargo only for a connection made to see them.
With the connection's key
| Parameter | In | Type | Meaning |
|---|---|---|---|
status | query | review | approved | scheduled | published | rejected | |
episodeId | query | string | |
cursor | query | string | |
limit | query | integer |
200A page ·object401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
get/clips/{id}One clip with its texts and links to its files (an hour)
With the connection's key
| Parameter | In | Type | Meaning |
|---|---|---|---|
id * | path | string |
200The clip ·ClipDetail401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409Under embargo (embargo, with its end) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Approval
post/clips/{id}/approveApproves the step a clip in review waits for
In the name of the person who answers for the connection; the audit log names the connection and by. Only a clip in review at stage moves: a repeated event or a second click gets 409 stale with where the clip is now, and nothing happens.
With the connection's key
| Parameter | In | Type | Meaning |
|---|---|---|---|
id * | path | string |
Body (JSON)
stage*integer– The step shown to whoever decided (approval.stage): nothing happens when the clip has moved oncommentstringbystring– Who clicked, as your tool knows them; kept in the audit log as reported
200What happened ·Decision401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409stale (the clip moved on) or embargo ·Failure422Invalid ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
post/clips/{id}/rejectSends a clip in review back
In the name of the person who answers for the connection; the audit log names the connection and by. Only a clip in review at stage moves: a repeated event or a second click gets 409 stale with where the clip is now, and nothing happens.
With the connection's key
| Parameter | In | Type | Meaning |
|---|---|---|---|
id * | path | string |
Body (JSON)
stage*integer– The step shown to whoever decided (approval.stage): nothing happens when the clip has moved oncommentstringbystring– Who clicked, as your tool knows them; kept in the audit log as reported
200What happened ·Decision401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409stale (the clip moved on) or embargo ·Failure422Invalid ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Episodes
get/episodes/{id}One episode: its show, embargo, analysis and clips
With the connection's key
| Parameter | In | Type | Meaning |
|---|---|---|---|
id * | path | string |
200The episode ·Episode401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure409Under embargo (embargo, with its end) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
Webhooks
get/hooksThe connection's webhooks
With the connection's key
200Its webhooks ·object401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
post/hooksSubscribes an address to events (the secret comes once)
Events come as a POST signed like the REST API's webhooks (ShowBits-Signature: t=…,v1=HMAC-SHA256 of t.body). They name objects by id only; read them here. At most 10 webhooks per workspace, with the API's.
With the connection's key
Body (JSON)
url*string– https, reachable from the internetevents*clip.approved | clip.deleted | clip.forwarded | clip.rejected | clip.submitted | clip.video_ready …[]descriptionstring
201Subscribed ·object401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure422Invalid, or an address ShowBits may not reach (target) ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure
delete/hooks/{id}Unsubscribes
With the connection's key
| Parameter | In | Type | Meaning |
|---|---|---|---|
id * | path | string |
204Gone401No or an unknown key ·Failure403The trial has ended (inactive), or nobody answers for the connection (owner) ·Failure404Unknown ·Failure429Too many requests a minute (tooMany), or a limit reached (limit) ·Failure