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

  1. Credentials → Add credential → Header Auth: name Authorization, value Bearer, a space and the key.
  2. An HTTP Request node with this credential: GET https://app.showbits.ai/api/automation/v1/me answers with the connection and its workspace.
  3. 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.
  4. Check the signature with the Crypto node (HMAC-SHA256 of t.body, raw body) and drop repeats by the event's id (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:

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

  • 200 The connection · Connection
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 429 Too 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

ParameterInTypeMeaning
statusqueryreview | approved | scheduled | published | rejected
episodeIdquerystring
cursorquerystring
limitqueryinteger
  • 200 A page · object
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 429 Too 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

ParameterInTypeMeaning
id *pathstring
  • 200 The clip · ClipDetail
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 Under embargo (embargo, with its end) · Failure
  • 429 Too 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

ParameterInTypeMeaning
id *pathstring

Body (JSON)

  • stage * integer – The step shown to whoever decided (approval.stage): nothing happens when the clip has moved on
  • comment string
  • by string – Who clicked, as your tool knows them; kept in the audit log as reported
  • 200 What happened · Decision
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 stale (the clip moved on) or embargo · Failure
  • 422 Invalid · Failure
  • 429 Too 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

ParameterInTypeMeaning
id *pathstring

Body (JSON)

  • stage * integer – The step shown to whoever decided (approval.stage): nothing happens when the clip has moved on
  • comment string
  • by string – Who clicked, as your tool knows them; kept in the audit log as reported
  • 200 What happened · Decision
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 stale (the clip moved on) or embargo · Failure
  • 422 Invalid · Failure
  • 429 Too 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

ParameterInTypeMeaning
id *pathstring
  • 200 The episode · Episode
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 409 Under embargo (embargo, with its end) · Failure
  • 429 Too many requests a minute (tooMany), or a limit reached (limit) · Failure

Webhooks

get/hooksThe connection's webhooks

With the connection's key

  • 200 Its webhooks · object
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 429 Too 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 internet
  • events * clip.approved | clip.deleted | clip.forwarded | clip.rejected | clip.submitted | clip.video_ready …[]
  • description string
  • 201 Subscribed · object
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 422 Invalid, or an address ShowBits may not reach (target) · Failure
  • 429 Too many requests a minute (tooMany), or a limit reached (limit) · Failure
delete/hooks/{id}Unsubscribes

With the connection's key

ParameterInTypeMeaning
id *pathstring
  • 204 Gone
  • 401 No or an unknown key · Failure
  • 403 The trial has ended (inactive), or nobody answers for the connection (owner) · Failure
  • 404 Unknown · Failure
  • 429 Too many requests a minute (tooMany), or a limit reached (limit) · Failure

Back to showbits.ai