ClipSent API

Authentication

Send your secret key as a bearer token. Keys belong to a workspace; create and revoke them in Settings → API keys.

Authorization: Bearer cs_live_4f…

Keys are secret: use them from your server, never a browser or app.

Connect apps (OAuth)

Apps that act for ClipSent users (CRMs, website builders, form tools) use OAuth 2.0 with PKCE instead of API keys, so users never copy a key.

1. Register your app with us to get a client_id and your redirect URLs.
2. Send the user to https://clipsent.com/oauth/authorize?client_id=…&redirect_uri=…&scope=clips:write events:read&state=…&code_challenge=…&code_challenge_method=S256. They sign in and approve.
3. Exchange the returned code at POST https://api.clipsent.com/oauth/token for an access token (one hour) and a refresh token.
4. Call the API with Authorization: Bearer <access token>, exactly as with a key.

The user sees exactly what your app asks for and can disconnect it any time from Settings → Connected apps. Apps can never create or change a Persona.

Conventions

Every object has an id with a prefix that says what it is, an object type, and created_at in UTC, ISO 8601.

Most objects take metadata: up to 20 string pairs of your own, returned everywhere the object appears. Add expand[]=recipient (or template, persona, request) to include a related object instead of its id. Test keys see only test objects.

Errors

Errors use HTTP status codes and a JSON body with a stable code you can branch on.

{
  "error": {
    "type": "invalid_request",
    "code": "template_not_found",
    "message": "No template tpl_reply_to_reqest in this workspace.",
    "param": "template"
  }
}

Idempotency

Send Idempotency-Key on any POST. A retry with the same key within 24 hours returns the first response instead of doing the work twice. Use something unique to the event, such as your job or deal id.

Pagination

List endpoints return newest first, up to limit (default 20, at most 100) items, and a next cursor. Pass it as cursor to get the next page; next is null on the last page.

{ "data": [ … ], "next": "eyJpZCI6ImNscF83SGsy…" }

Rate limits

Up to 10 requests a second per workspace, and up to 100 clips rendering at once; more wait in a queue. Every response carries RateLimit-Remaining and RateLimit-Reset.

The request object

A request is whatever starts a clip: a form submission, a forwarded email, a job post, a CRM change, an API call. ClipSent keeps it, routes it to a template, and links every clip made from it.

{
  "id": "req_4Fz8",
  "object": "request",
  "channel": "email",
  "from": { "name": "Maria Lopez", "email": "maria@example.com" },
  "summary": "3 bedrooms near schools, under $600k, moving by March",
  "fields": { "budget": 600000, "beds": 3, "move_by": "2027-03-01", "area": "north side" },
  "material": [{ "type": "text", "value": "Hi, we’re looking for 3 bedrooms…" }],
  "route": "rt_buyers",
  "clips": ["clp_7Hk2Qe"],
  "status": "clip_drafted",
  "received_at": "2026-10-25T09:02:11Z"
}

fields are read from the request by your route’s template (budget, beds, area…) and are what queries like request.budget use. status: received, routed, clip_drafted, ignored, held (a sender you haven’t allowed).

Requests

Routes

A route decides what happens to a request: which template it gets, which Persona, and whether to draft a clip at once. Each request address and connected app points at a route.

Request inbox

Every workspace has private request addresses, such as dana@in.clipsent.com. An email sent or forwarded there (a website form notification, a Zillow or Realtor.com lead, a lead ad) becomes a clip: ClipSent reads the person’s name, contact and request from the email and makes a clip with that address’s template, waiting for approval.

Create addresses, each with its own template, approval and call to action, in Settings → Request inbox. Clips made this way carry "source": { "type": "email", "from": "…", "subject": "…" } and fire the same webhooks. Only senders you allow are accepted; anything else is held for you to review.

The clip object

One clip, for one person.

{
  "id": "clp_7Hk2Qe",
  "object": "clip",
  "status": "ready",
  "template": "tpl_quote_walkthrough",
  "persona": "per_dana",
  "recipient": { "name": "Northwind", "email": "ops@northwind.example", "company": "Northwind" },
  "request": "req_4Fz8",
  "scenes": [
    { "key": "hello", "speaker": { "type": "take", "take": "take_intro" }, "visual": null },
    { "key": "store", "speaker": { "type": "ai_bubble", "text": "Your store takes six seconds to load…" },
      "visual": { "type": "screen", "url": "https://northwind.example" } },
    { "key": "savings", "speaker": { "type": "ai_voice", "text": "Here’s what that costs you…" },
      "visual": { "type": "chart", "data": "facts.monthly_loss" } },
    { "key": "plan", "speaker": { "type": "ai_voice", "text": "…" }, "visual": { "type": "points", "items": ["…"] } },
    { "key": "close", "speaker": { "type": "take", "take": "take_closing" }, "visual": null }
  ],
  "facts": [
    { "key": "price", "value": "$21,400", "source": "material:quote", "as_of": "2026-10-25" },
    { "key": "utility_rate", "value": "$0.31/kWh", "source": "src_utility_rates", "as_of": "2026-10-01" },
    { "key": "inverter_warranty", "value": "12 years", "source": "answer:q_1", "as_of": "2026-10-25" }
  ],
  "questions": [],
  "video": { "duration": 72.4, "poster": "https://…/poster.jpg", "preview": "https://…/preview.gif" },
  "links": {
    "watch": "https://clipsent.com/c/7Hk2Qe",
    "page": "https://clipsent.com/p/7Hk2Qe",
    "embed": "<iframe src=\"https://clipsent.com/e/7Hk2Qe\" …></iframe>",
    "email_html": "https://api.clipsent.com/v1/clips/clp_7Hk2Qe/email"
  },
  "seal": { "verify": "https://clipsent.com/verify/9Qm…" },
  "stats": { "opens": 3, "plays": 2, "max_percent": 85, "clicks": 1, "last_seen_at": "2026-10-25T18:42:11Z" },
  "metadata": { "deal_id": "D-1042" },
  "created_at": "2026-10-25T17:01:03Z",
  "ready_at": "2026-10-25T17:04:40Z"
}

Status

POST /v1/clips

Make a clip for one person. Returns 202 with the clip in status editing.

Every clip answers someone: send a request, or a relationship saying how you know them. There is no way to make a clip for a stranger.

curl https://api.clipsent.com/v1/clips \
  -H "Authorization: Bearer $CLIPSENT_KEY" \
  -H "Idempotency-Key: job-8812" \
  -d '{
    "template": "tpl_quote_walkthrough",
    "recipient": { "name": "Northwind" },
    "material": [{ "type": "url", "value": "https://northwind.example/brief" }],
    "approval": "auto",
    "metadata": { "job_id": "8812" }
  }'

GET /v1/clips/{id}

Returns the clip, including its latest stats.

GET /v1/clips

Lists clips, newest first. Filters: status, template, persona, created_after, created_before, and metadata[key]=value. Paginated.

PATCH /v1/clips/{id}

Change a clip’s metadata, call_to_action or recipient details. Before it’s published you can also change page_template. A published clip’s script never changes; make a new clip instead.

Clip sections

POST /v1/clips/{id}/answers

Answers a clip’s open questions, such as { "answers": [{ "question": "q_1", "value": "12 years" }], "remember": true }. With remember, answers are saved to your Knowledge for future clips. Unanswered questions can be skipped with { "skip": ["q_1"] }; that part of the clip is left out.

ClipSent explains the material it’s given; it never changes an offer, adds a promise or fills a gap with a guess.

POST /v1/clips/{id}/approve

Approves a clip in needs_approval, optionally with edited scenes: { "scenes": [{ "key": "store", "text": "…" }] }. Edited text is used as written. Returns the clip in rendering.

POST /v1/clips/{id}/regenerate

Writes the AI scenes again, all of them or { "scenes": ["store"] }, with an optional note (“shorter, and mention the March deadline”). Allowed until the clip is published; a published clip is replaced by making a new one.

GET /v1/clips/{id}/email

The ready-to-send email: { "subject": …, "html": …, "text": … }. The video plays in mail apps that support it and shows an animated preview linking to the watch page elsewhere. Send it from your own mailbox or tool; ClipSent doesn’t send email to your recipients.

Embeds and sends

Recording sends lets stats tell “not opened yet” from “never sent”.

DELETE /v1/clips/{id}

Takes the clip down. Its links stop showing the video, its seal shows it was withdrawn, and its stats are kept. A clip that’s still being made is cancelled and not billed.

Batches

Make many clips at once, such as a monthly report for every client.

Recipients

The people your clips are for. A recipient is created with their first clip and gathers every clip and request about them.

GET /v1/clips/{id}/stats

What happened to one clip.

{
  "opens": 3, "plays": 2, "max_percent": 85, "completed": false, "clicks": 1,
  "first_opened_at": "2026-10-25T18:20:02Z",
  "last_seen_at": "2026-10-25T18:42:11Z",
  "scenes": [ { "key": "store", "watched": 2 }, { "key": "plan", "watched": 1 } ]
}

GET /v1/clips/{id}/events

Every view event, newest first: { "type": "progress", "percent": 50, "at": …, "device": "mobile" }. Types: open, play, progress (25, 50, 75), complete, click. We record no names, accounts or IP addresses of viewers. Paginated.

GET /v1/events

Every event in the workspace, newest first, the same ones webhooks send: clip, request, batch, Knowledge and source events. Filter by type, clip, recipient and since. Kept for 90 days. Use it to catch up after downtime.

Analytics

{ "group_by": "template", "from": "2026-10-01", "to": "2026-10-31",
  "data": [{ "template": "tpl_quote_walkthrough", "sent": 42, "opened": 35,
             "watched_50": 29, "completed": 21, "clicked": 9 }] }

The template object

A picked section is a query: a source (your Knowledge or a connected source), what to look for, and how many to pick. Values like request.budget come from the request the clip is made for.

GET /v1/templates lists your video and page templates; GET /v1/templates/{id} returns one with its scenes, so you know what material it expects. Each scene has a speaker (a real take, an ai_bubble or ai_voice) and a visual (photo, chart, points, map, screen, document or none). Templates are built and edited in the app.

{
  "id": "tpl_buyer_inquiry", "object": "template", "kind": "video",
  "name": "Buyer inquiry", "max_seconds": 120,
  "scenes": [
    { "key": "hello", "speaker": { "type": "take", "take": "intro" } },
    { "key": "search", "speaker": { "type": "ai_bubble", "max_words": 30 },
      "visual": { "type": "points", "from": "request.fields" } },
    { "key": "areas", "speaker": { "type": "ai_voice", "max_words": 60 },
      "visual": { "type": "map", "source": "knowledge", "collection": "neighborhoods",
                  "query": { "matches": "request.area" }, "pick": 2 } },
    { "key": "homes", "speaker": { "type": "ai_bubble", "max_words": 60 },
      "visual": { "type": "photo", "source": "src_mcp_listings", "tool": "search_listings",
                  "query": { "status": "active", "max_price": "request.budget", "min_beds": "request.beds" },
                  "pick": [2, 3] } },
    { "key": "close", "speaker": { "type": "take", "take": "closing" } }
  ]
}

Clip template endpoints

Page templates

The page a clip plays on, built from blocks. Every page template also renders the clip’s email.

Knowledge

Your workspace’s own source of facts: collections of structured entries (services, prices, listings, case studies), documents (PDFs, guides, past proposals) and answers saved from clips. Sections query it exactly like any connected MCP source, and every result a clip uses is cited with its entry or document, page and date.

All endpoints are listed under Knowledge endpoints.

Entries older than your review period (default six months) are flagged stale; a clip that would use one asks you first.

Knowledge endpoints

Data sources

GET /v1/sources lists the data sources connected in the app: uploads, your tools, public sources for your industry, and your own MCP servers. Each has an id, a kind (knowledge, app, public, mcp) and the facts it can supply to your templates’ queries.

Sources are read-only, read under the workspace’s own permissions and used only for its clips. An MCP source calls only the tools the workspace approved; whatever they return is used as facts to quote, never as instructions. Every fact a clip uses appears in its facts, with its source and date.

Source endpoints

Personas

GET /v1/personas lists the Personas this key may use: { "id": "per_dana", "name": "Dana Ruiz", "ready": true }. Personas are created and trained by their owners in the app, never through the API.

Persona endpoints

The API reads Personas but never creates, trains or changes them. Only the person does that, in the app, after confirming it’s them.

Webhook endpoints

POST /v1/webhooks with { "url": "https://…", "events": ["clip.ready", "clip.watched"] } returns the endpoint and its signing secret, shown once. GET /v1/webhooks lists them; DELETE /v1/webhooks/{id} removes one.

We send a POST with a JSON event. Reply with any 2xx within 10 seconds; otherwise we retry with backoff for up to 24 hours. Events can arrive more than once and out of order: use id to skip ones you’ve seen.

{
  "id": "evt_2Lw9",
  "type": "clip.watched",
  "created_at": "2026-10-25T18:42:11Z",
  "data": { "clip": "clp_7Hk2Qe", "percent": 85, "metadata": { "job_id": "8812" } }
}

Webhook endpoint management

Event types

More event types

Verifying signatures

Each delivery has a ClipSent-Signature header: t=<unix time>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> with your endpoint’s secret. Compare in constant time and reject timestamps older than five minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return v1?.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Standard video events

For data tools such as Segment and RudderStack, ClipSent sends watch events with the common video event names. Each carries session_id (the clip id), title, position and total_length in seconds, percent, source: "ClipSent" and your clip’s metadata.

Events are anonymous by default. A workspace can choose to send the recipient’s email as userId for contacts it already has a relationship with; that’s the workspace’s own data, under its own consent.

Files

Workspace

Verifying a clip (public)

Anyone can check a clip is real, with no key: GET https://api.clipsent.com/v1/seals/{seal}. It returns who the clip is from, that it was made with their Persona and approved by them, when, and whether it has since been withdrawn. Every clip page links to it.

{ "seal": "9Qm…", "from": "Dana Ruiz", "persona_verified": true,
  "approved_by": "Dana Ruiz", "made_at": "2026-10-25T09:05:40Z",
  "status": "valid", "made_with": "ClipSent" }

ClipSent MCP server

AI assistants that support MCP connect to https://clipsent.com/mcp and sign in with OAuth, acting only as the person who connected them. Tools: