API reference

Clips

A clip is a moment Clipped found. Ask for them with a cursor: the answer carries a new one, and passing it back gives you only what has happened since. A cursor never skips a clip, which is the thing an offset cannot promise while clips are being written; a clip comes back again when it changes, such as when it is cut or posted.

A clip that changes — it is posted, or given a better title — moves to the end of the feed again, so a cursor sees that as well.

Each clip has a video URL. Fetch it with the same key — it is an mp4 and supports range requests, so you can pull part of one without the whole file. Most clips are cut only when somebody asks for one, so cut says whether the mp4 exists yet: fetching the video of an uncut clip starts the cut and answers 202 with Retry-After until it is ready, usually within a minute. Clips that post themselves are cut straight away.

Each clip also has a thumbnail: a still from the middle of it, a small WebP at a public address you can put straight in a page, with no key. It is the same field in the feed, in a webhook's clip and in a live feed's moment. It is null until the still is made — a moment after a clip is cut, a few minutes after an uncut one is found, once the VOD has that part of the stream — and the clip comes back in the feed when it arrives. Not waiting for that: GET /api/v1/clips/{id}/thumbnail (with your key) makes it if it can and redirects to it, so it is the address to use when thumbnail is null, and it follows the clip to its new still if it is cut again.

Endpoints

GET/api/v1/clips

Clips, oldest first.

cursor, channel, limit (1–100, default 25). No cursor: the newest few, and a cursor to poll from.

GET/api/v1/clips/{id}

One clip.

GET/api/v1/clips/{id}/video

The mp4.

Supports Range. 202 with Retry-After while it is being cut.

GET/api/v1/clips/{id}/thumbnail

Its thumbnail.

Redirects (302) to the image, making it first if there is none. 202 with Retry-After while it can't be made yet.

Fields

A clip

idstring

<session>:<moment>. Opaque; URL-encode it in a path.

channelstring

Whose stream it is from. displayName is how they write it.

gamestring | null

What they were playing.

titlestring | null

The written title, once there is one.

summarystring | null

A line about what happens.

categorystring | null

What kind of moment: funny, clutch, rage, …

scorenumber

0–100: how good a moment it is.

startedAtnumber

When it happened, in wall-clock ms.

secondsnumber | null

How long the clip is.

cutstring

ready, cutting, or uncut — cut when video is fetched.

videostring

Where the mp4 is.

thumbnailstring | null

A still from the middle of it: a small WebP (480px wide) at a public URL, no key needed. null until it is made — a moment after a clip is cut, a few minutes after an uncut one is found — and the clip comes back in the feed when it is. GET /api/v1/clips/{id} and …/thumbnail make it there and then.

publishedobject | null

By destination: { status, url }. status is published, drafted (waiting in TikTok), uploading or failed.

atstring

When it last changed, ISO 8601.

Examples

The polling loopShell

# First call: what is there, and a cursor.
curl "https://app.clipped.so/api/v1/clips?limit=5" -H "Authorization: Bearer $KEY"

# Every call after: only what is new.
curl "https://app.clipped.so/api/v1/clips?cursor=$CURSOR" -H "Authorization: Bearer $KEY"

A clip's thumbnail, saved to a fileShell

# -L follows the redirect to the image. A 202 means it isn't made yet: try again in a minute.
curl -L "https://app.clipped.so/api/v1/clips/$CLIP_ID/thumbnail" -H "Authorization: Bearer $KEY" -o thumbnail.webp

Use cases

Gallery or dashboardShow new clips in your own app Event-driven backendBe told the moment a clip is ready Editor in the loopPick the clips yourself, then post them