Video Clipping API for AI Agents: Upload to Receipts

Everpop's REST API lets an AI agent run the whole short-video loop on a creator's own file: upload the video, start clips, poll the job, publish to exact connected accounts once the user confirms, then read receipts for eligible YouTube Shorts at 48 hours and 7 days. It needs a Pro or Scale plan and a Bearer key.

The contract is an OpenAPI 3.1 spec, and skill.md walks an agent through every call.

What does an agent need before the first API call?

An agent needs an Everpop API key on a Pro ($49/mo) or Scale (from $149/mo) account; Free and Starter accounts can connect, but requests return 402. The user creates the key on the API page of the studio, and the agent sends it as Authorization: Bearer epk_… on every request, never in a URL.

Keys are Full (read + write), the default, or Read-only, which can call every GET endpoint and gets 403 scope on a write. Example: a reporting agent that reads receipts gets a read-only key, so a bug in it cannot post.

How does the upload-to-publish loop work, step by step?

The loop is nine requests, from a usage check to receipts:

How does an agent upload a video file to the API?

An agent requests an exact-size upload slot, PUTs exactly those bytes with every requiredHeaders entry (Content-Type, If-None-Match: *), then finalizes. Accepted files are .mp4, .mov, .webm, .mkv or .m4v, up to 32 GB on Pro and Scale. POST /api/v1/videos/upload takes a file up to 5 GB, the most one PUT can carry; for a bigger file it answers 413 file_too_large with reason single_put and a browserUploadUrl, where the user uploads it.

POST /api/v1/videos/complete takes the slot's key and rightsConfirmed: true, the user's own answer that they hold the rights, asked and never inferred. On active plans clipping then starts on its own (autoClipping: true). An agent that will call /clip with its own options sends renderMode: "manual"; otherwise the automatic render uses that video's allowance and the later /clip uses another.

Example: a retried PUT answers 412. The bytes are already stored, since If-None-Match: * refuses to overwrite, so skill.md says to call /videos/complete with the same key rather than upload again.

Which clip options can an agent set?

An agent sets clip count, frame, captions and spoken language on POST /api/v1/clip; anything omitted falls back to the account's saved choices.

• clipCount: 1 to 20, capped by the plan's clips per video (Pro 10, Scale 15). Read clipCountApplied.
• aspectRatio: 9:16, 1:1, 16:9 or 4:5. captionsEnabled switches burned-in captions for this render.
• language: the language spoken in the video, not the one you want to read.
• An Idempotency-Key header stops a retry from starting a second render.

Example: a Bulgarian interview gets "language": "bg" for Bulgarian captions, or null for English ones. Sending "en" tells the recognizer to hear English and leaves the clip nearly caption-less.

Then poll GET /api/v1/jobs/{id} until status leaves PENDING or PROCESSING; on COMPLETED, each clip carries a clipId and a review block (quality warnings, hook, captions) to show the user.

How does an AI agent publish clips to Shorts, Reels and TikTok?

An agent publishes to YouTube Shorts, Instagram Reels, Facebook Reels and TikTok (as an inbox draft) by naming exact connected destination ids, showing the user every account and field, and calling POST /api/v1/publish after an explicit yes. GET /api/v1/publish lists each account's id, platform and name; there is no publish-to-all.

The request takes clipId, destinationIds and metadata (title, description, privacyStatus). private or unlisted needs every destination to be YouTube; otherwise the request returns 422 and nothing publishes. ok: true means Everpop accepted the request, so the agent checks each posts[].status and follows in-flight posts with GET /api/v1/posts?clipId= until each is final.

Example: a TikTok destination ends at DELIVERED, meaning a ready-to-post draft sits in the account's inbox and going public stays the creator's tap. Hands-free posting needs an autopilot rule the user switched on; without one, this is review-first posting: the agent carries, the human decides.

How does an agent report results after publishing?

GET /api/v1/receipts returns aggregate YouTube Analytics numbers for eligible YouTube Shorts at 48 hours and 7 days: views, average view percentage and subscribers gained, with a token-protected link per Short. Instagram Reels and Facebook Reels publish and TikTok gets inbox drafts, but none of them is measured today.

Example: at 48 hours the 7-day window is still null, so the agent checks again later. Pass nextCursor back as ?cursor= for older pages. Why a link beats a screenshot: receipts versus screenshots.

Agencies run the same loop across client channels: Scale covers 10 YouTube channels, and Pro and Scale include the API, MCP and Campaign Mode. POST /api/v1/campaigns creates a campaign, /campaigns/{id}/attach adds published posts and /campaigns/{id}/proof returns its measured report, with ?csv=1 for a spreadsheet (skill.md).

Which API errors should an agent handle?

Everpop's API errors carry a stable code; branch on it, and treat an unknown code by its HTTP status. From skill.md and the changelog in openapi.json:

Can an agent run the same loop over MCP?

Yes. Everpop's MCP server at https://everpop.app/api/mcp/mcp exposes 13 tools over Streamable HTTP for the same loop, from request_upload to list_receipts. MCP is an open-source standard for connecting AI applications to external systems. Clients sign in with OAuth 2.1 + PKCE or the same Bearer key, and publish_clip is marked destructive so clients can ask before it runs. Clips started over MCP stay drafts even with Autopilot on. The official MCP Registry lists it as app.everpop/everpop.

Example: in a chat app without file access, the user uploads in the studio or a linked Google Drive folder, and the agent continues from list_videos.

What can't the Everpop API do?

The Everpop API cannot clip a link: Everpop never downloads from YouTube. It does not measure Reels or TikTok posts. And it will not publish to accounts nobody named.

Claims table