Integrations

Publish to spirkz from any scheduler

The Integrations API lets third-party schedulers — Zapier, Metricool, Buffer and the like — submit videos to spirkz on a creator's behalf. A video sent here goes through the same rules and the same review queue as one uploaded in the app.

Base URL: https://server.spirkz.com/api/v1/integrations

How it works

1
The creator creates an API key in the spirkz app and pastes it into the scheduler.
2
The scheduler calls POST /videos with a public videoUrl and the details. spirkz answers 202 at once.
3
spirkz downloads the file in the background, stores it, and creates a pending submission for the creator.
4
The spirkz team reviews it. If it's approved and scheduledAt is still ahead, it goes live at that time; otherwise it goes live immediately.
5
The scheduler polls GET /videos/:id for progress.

Authentication

Send the creator's key on every request. A missing, unknown or revoked key gets 401. Keys act as the creator who issued them.

Authorization: Bearer spk_...

Rate limits, per key

600

requests per hour, overall

POST /videos calls per hour

Endpoints

GET/me

Connection test. Call it right after the creator pastes their key.

{ "user": { "id", "name", "username" }, "keyName" }

GET/categoriesGET/languages

Data for your pickers: valid categoryIds (active categories; ?locale= for names) and languageSlug values.

POST/videos

Submit a video. The body is JSON:

Field		Rules
videoUrl	Required	`https`, publicly reachable, ≤ 2000 chars. mp4 / mov / webm / avi, ≤ 500 MB. Private or internal addresses are refused.
source	Required	Who is sending, e.g. `"zapier"`, `"metricool"`. ≤ 50 chars, stored lowercased.
name	Required	≤ 150 chars.
categoryIds	Required	1–5 ids from `GET /categories`.
description	Optional	≤ 500 chars.
languageSlug	Optional	From `GET /languages`. Default `en`.
tag	Optional	Array of strings, up to 10 tags, each ≤ 40 chars.
duration	Optional	Seconds, non-negative integer.
scheduledAt	Optional	ISO 8601. At least 10 minutes and at most 60 days ahead. Omit or `null` = live on approval.

202 — data.video with status: "received".
400 / 404 — a field is invalid. Nothing is stored.
409 — the creator already has 10 videos awaiting submission or review (including ones still downloading).

GET/videosGET/videos/:id

The creator's integration videos, newest first (?limit, ?offset), or one by id.

{
  "id": "...",
  "source": "zapier",
  "video_url": "https://...",
  "status": "submitted",
  "error": null,
  "created_at": "...",
  "updated_at": "...",
  "userVideo": {
    "id": "...",
    "name": "...",
    "status": "pending",
    "scheduled_at": "2026-10-10T09:00:00.000Z",
    "decline_reason": null,
    "publishedVideoId": null
  }
}

Tracking a video

Download — `status`

receivedprocessingsubmittedorfailed

On failed, the reason is in error.

Review — `userVideo.status`

pendingscheduledapprovedordeclined

publishedVideoId is set once the video is live. A declined video carries a decline_reason.

Example

curl -X POST https://server.spirkz.com/api/v1/integrations/videos \
  -H "Authorization: Bearer spk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/clip.mp4",
    "source": "zapier",
    "name": "Morning routine",
    "categoryIds": ["<category id>"],
    "description": "Day 1",
    "scheduledAt": "2026-10-10T09:00:00Z"
  }'

Native support

Any scheduler can integrate with the endpoints above. These tools already support spirkz out of the box:

NativegenzlSupports spirkz natively — connect your API key and schedule.genzl.com →

Building an integration?

Tell us what you're making and we'll help you ship it.

Email us