For your own tools
Upload from your build, not the browser.
Push banners to Previewer from your terminal, a build script or CI, and check on approvals, with one command. All it needs is Node.js. Building your own integration? The API underneath is small and documented below.
1Install
npm install -g previewer-agencyNeeds Node.js 20.11 or newer. This gives you the
previewercommand; or skip it and putnpx previewer-agencyin front of each command.2Sign in
previewer loginOpens your browser. Type the code from your terminal and approve; this computer gets its own token.
3Push a folder
previewer push ./dist --client "Acme" --campaign "Spring sale"ZIPs, banner folders, images, videos and backup images. A file with the same name replaces the banner as a new version.
4Send the link
previewer statusPush prints the preview link and copies it.
statusshows approvals and when your client last looked.
Command line tool
Install
Needs Node.js 20.11 or newer; check with node --version.
Without installing, put npx previewer-agency in front of each command, as in the examples on this page. npx fetches the latest version the first time.
On your computer, for the shorter previewer command (run it again later to update):
npm install -g previewer-agency
previewer --versionEvery example then works with previewer instead of npx previewer-agency, for example previewer push ./dist.
In a project, so everyone on it uses the same version:
npm install --save-dev previewer-agencyThen add a script to package.json, "preview": "previewer push dist", and run npm run preview.
Sign in
npx previewer-agency loginOpens your browser. Type the code your terminal shows and approve (it is never in the link, so nobody can send you a link that signs them in). You get an email about it. Your computer gets its own token: it can do what you can do in Previewer (owners and editors: upload, generate backups, create clients and campaigns, remove or hide banners, set a note or a preview password; viewers: look and download), stops working if your access ends, and shows under API in the admin, where an owner can revoke it. previewer logout revokes it yourself.
The token is saved in ~/.config/previewer/config.json, readable only by you.
Push a folder
npx previewer-agency push ./dist --client "Acme" --campaign "Spring sale"What it picks up:
| In the folder | Becomes |
|---|---|
300x250.zip | an HTML5 banner |
300x250/ with an index.html | an HTML5 banner (zipped for you) |
300x250.jpg next to 300x250.zip, or anything in backups/ | that banner's backup image |
| other images and videos | image and video creatives |
Leave out --client and --campaign and push lets you pick them from a menu: arrow keys to move, type to filter, Enter to choose, or + New campaign to make one.
A file with the same name as a banner already in the campaign replaces it as a new version. If the campaign doesn't exist yet, push offers to create it (--create skips the question). Large files and big batches are split up for you.
The first push saves the campaign in .previewer.json in the current folder (ids, names and the site address; safe to commit, it never holds a token). A token is only ever sent to the site you chose yourself: PREVIEWER_TOKEN goes to --site, PREVIEWER_URL or previewer.agency, never to a site a .previewer.json names. Addresses other than https:// are refused, except http://localhost. After that:
npx previewer-agency push ./distWhen it's done it prints the preview link and copies it to your clipboard. --open opens it. --dry-run shows what would go up, and to which client and campaign, without uploading.
After the upload, push lists what the upload check found: a hard-coded link instead of a clickTag, a banner over the weight budget, a missing ad.size tag. Fix it and push again; the same file name replaces the banner. --backups also generates the backup image of every HTML5 banner that has none.
A --client you name has to own the campaign. In a folder linked to one client's campaign, push --client "Another client" stops before anything is uploaded; add --campaign to say which campaign of that client you mean.
Check on it
npx previewer-agency status # approvals per banner, backups, checks, when the client last looked
npx previewer-agency open # open the preview
npx previewer-agency campaigns # list campaigns (--client to narrow)
npx previewer-agency link # choose this folder's campaign without uploading
npx previewer-agency whoami--json gives machine-readable output for status, wait, campaigns and whoami.
Backups, approval and hand-off
npx previewer-agency backups # generate the backup images that are missing
npx previewer-agency backups --all # make every one again
npx previewer-agency wait --timeout 240 # wait until your client approved everything
npx previewer-agency download ./handoff --approved- `backups` has Previewer play each HTML5 banner to its end frame and save it as a JPG within the size limit, like Generate backups in the admin. One banner takes about as long as it plays.
- `wait` checks every 15 seconds and exits
0once everything is approved,2when the time is up (default 60 minutes), or3when there is nothing to wait for (the campaign doesn't ask for approvals, or has nothing your client can approve). In a script:previewer wait && previewer download ./handoff --approved. - `download` saves one ZIP with every creative and its backup image, laid out like Download all in the admin.
--approvedleaves out what your client hasn't approved yet, and anything you hid from the preview. If a ZIP with that name is already in the folder, the new one gets a number:… (2).zip.
In CI
Create a token under API in the admin (Upload access, narrowed to a client or campaign if you like), store it as a secret, and:
PREVIEWER_TOKEN=pvw_… npx previewer-agency push dist --campaign 42 --backupsPREVIEWER_URL points it at another Previewer address.
With an AI agent
previewer mcp runs Previewer as an MCP server, so an agent like Claude Code or Cursor can upload, read what the upload check found and fix it, generate backups, wait for approval, download the approved set and set up a project for you. It uses the same sign-in as the command line; if this computer isn't signed in yet, the agent starts the sign-in, and you type its code in your browser and approve.
Claude Code:
claude mcp add previewer -- npx -y previewer-agency mcpCursor, Windsurf, Claude Desktop and others, in their MCP settings:
{ "mcpServers": { "previewer": { "command": "npx", "args": ["-y", "previewer-agency", "mcp"] } } }Then ask things like "upload dist to the Acme spring campaign, fix whatever the check complains about, make the backups and give me the link", "which banners are still waiting for approval?" or "download what's approved into ./handoff".
| Tool | What it does |
|---|---|
whoami, sign_in | Which account this computer is signed in to; start a sign-in |
list_clients, list_campaigns | What the token can reach |
get_campaign | Preview link, approvals (with the name your client gave), backups, and what the upload check found per banner |
upload_folder | Upload a folder; returns the preview link and what the check found in the uploaded banners |
generate_backups | Generate the backup images that are missing (or all of them) |
wait_for_approval | Wait for your client, up to about 45 seconds per call, and report where approvals stand |
download_campaign | Save the creatives and backups as one ZIP, optionally only the approved ones |
create_client, create_campaign, link_folder | Set up a client, a campaign, and the folder's link to it |
set_note | The note at the top of the preview, for example what changed this round |
update_banner | Hide a banner from the preview or show it again; put it in a group |
set_preview_password | Put a password on a preview, or remove it |
remove_banner | Remove one banner |
Approving is left to your client, in the preview: no tool can approve. Creating, changing and removing need Manage access; uploading and generating backups need Upload; the rest works with a read-only token.
To have an agent set up a project from scratch, point it at previewer.agency/llms.txt.
As a library
import { PreviewerClient } from 'previewer-agency';
import { collectUploads } from 'previewer-agency/files';
const api = new PreviewerClient({ baseUrl: 'https://previewer.agency', token: process.env.PREVIEWER_TOKEN });
const { items } = await collectUploads('./dist');
const { campaign } = await api.upload(42, items);
console.log(campaign.previewUrl);
// What the upload check found, per banner:
for (const banner of campaign.banners) {
if (banner.checks?.status === 'fail') console.log(banner.label, banner.checks.items.filter((item) => item.status === 'fail'));
}
await api.generateBackup(42, '300x250');Also on the client: createClient, createCampaign, setNote, updateBanner, setPreviewPassword, removeBanner and download.
The API itself is documented at previewer.agency/docs/api.
API
Tokens
An account owner creates tokens under API in the admin (/admin/api). A token:
- belongs to the account, not to the person who created it;
- has an access level: Read only (list, read and download), Upload (also upload creatives and backup images, and generate backups) or Manage (also create clients and campaigns, remove, hide and group banners, and set a campaign's note and preview password);
- can be narrowed to one client or one campaign, so a freelancer or a studio only reaches what you give them;
- can expire (30 days, 90 days, 1 year or never), and can be revoked at any time;
- is shown once, when it is created. Previewer stores only a hash.
No token can approve a banner or change an approval, rename a campaign, change its look, its approval setting or its preview link, replace all banners, or delete a campaign or client. That stays in the admin, and approving stays with your client.
previewer login makes a personal token instead: approved by someone signed in, it belongs to them, gets their own access level (owners and editors: Manage, viewers: Read only), and stops working when they are deactivated, removed or reset their password. Owners see these in the list with the person's email.
Send the token on every request:
Authorization: Bearer pvw_…A missing, unknown, revoked or expired token, or one whose account is paused, gets 401. A campaign outside the token's scope gets 404 (never 403, so ids can't be probed). A token without the access level an endpoint needs gets 403. The level is noted next to each endpoint below; without a note, any token will do.
Endpoints
GET /api/v1/me
Which token this is and what it can do. Use it to test a token.
{
"token": { "name": "CI", "permission": "upload", "clientId": null, "campaignId": null },
"account": { "id": 7, "name": "Studio" }
}DELETE /api/v1/me revokes the token itself (what previewer logout does).
GET /api/v1/clients
The clients the token can reach: { "clients": [{ "id": 6, "name": "Acme", "campaignCount": 4 }] }.
POST /api/v1/clients (Manage)
Create a client: { "name": "Acme" } → 201 with { "client": { "id": 9, "name": "Acme", "campaignCount": 0 } }. Only the name; the logo, colours and approval default are set in the admin. A name that already exists (ignoring case) gets 409 with the existing client in client, so a script that runs twice doesn't make two. A token narrowed to one client or campaign can't create clients (403).
GET /api/v1/campaigns
Every campaign the token can reach, most recently saved first. ?client=<id> narrows it to one client.
{
"campaigns": [
{
"id": 42,
"name": "Spring sale",
"client": { "id": 6, "name": "Acme" },
"previewUrl": "https://studio.previewer.agency/campaign/k3x9…",
"revision": 12,
"updatedAt": "2026-11-19T09:12:00.000Z",
"bannerCount": 8,
"reviewableCount": 7,
"approvedCount": 3,
"lastViewedAt": "2026-11-19T10:01:00.000Z"
}
]
}reviewableCount is how many of the banners the client can approve (external links and banners hidden from the preview don't count), so a campaign is fully approved when approvedCount equals it. Both are null when the campaign doesn't ask for approvals.
POST /api/v1/campaigns (Manage)
Create a campaign: { "clientId": 6, "name": "Spring sale" } → 201 with { "campaign": … } as below. A token narrowed to one campaign can't create others (403).
GET /api/v1/campaigns/{id}
One campaign, as above, plus its note, whether the preview has a password, the newest client approval and its banners:
{
"campaign": {
"id": 42,
"…": "…",
"approvalsRequired": true,
"lastApprovedAt": "2026-11-19T10:05:00.000Z",
"note": "Round 2: new logo",
"passwordProtected": false,
"banners": [
{
"id": "300x250-spring-300x250",
"label": "300x250 · spring",
"kind": "html",
"width": 300,
"height": 250,
"status": "approved",
"approvedAt": "2026-11-19T10:05:00.000Z",
"approvedBy": "Anna Jansen",
"updatedAt": "2026-11-18T16:40:00.000Z",
"sizeBytes": 148213,
"hasBackup": true,
"hidden": false,
"group": "Dutch",
"checks": {
"status": "warn",
"weightBudgetKb": 150,
"platform": "Campaign Manager 360",
"initialLoadKb": 141,
"zipKb": 162,
"fileCount": 7,
"items": [
{ "id": "zip-weight", "label": "ZIP weight", "status": "warn", "detail": "162 KB of 150 KB · 12 KB over." },
{ "id": "file-count", "label": "File count", "status": "pass", "detail": "7 files." }
]
}
}
]
}
}checks is what the upload check found, for HTML5 banners; it is null for images, videos and links. Its status is the worst of the items: fail needs fixing (a hard-coded link instead of a clickTag, for example), warn needs a look (over the weight budget), pass is fine. An item's own status can also be info, a note. The weight items are held against the campaign's weight budget (weightBudgetKb, 150 KB unless set in the campaign settings). The checks read the code; they don't run the banner on the ad platform.
group is the name of the group the banner is shown under on the preview, or null. lastApprovedAt is when your client last approved something, so a script can tell whether anything happened since it last looked.
hidden is true for a banner the agency hid from the client's preview in the admin. It is still listed here, but the client doesn't see it, can't approve it, and it isn't counted in approvedCount.
kind is html, image, video or external; status is review or approved.
PATCH /api/v1/campaigns/{id} (Manage)
Change the note shown at the top of the preview: { "note": "Round 2: new logo" }; "" removes it. Response: { "campaign": … }. Nothing else about a campaign can be changed here.
PUT /api/v1/campaigns/{id}/password (Manage)
Put a password on the preview: { "password": "…" } → { "passwordProtected": true }. Setting one again, even the same one, locks out everyone who had unlocked the preview. DELETE on the same address removes the password. Only a hash is stored, so nothing can read a password back.
GET /api/v1/campaigns/{id}/download
One ZIP with the campaign's creatives and their backup images, laid out like Download all in the admin (groups as folders, backups next to the creatives). The response is the file itself (application/zip), not JSON.
?only=approvedleaves out everything your client hasn't approved: what goes to the media agency. These are the bannersapprovedCountcounts, so one you hid from the preview is left out too.?banners=<id>,<id>picks banners by id.
Without ?only=approved, banners hidden from the preview are included (this is your own download, not your client's). Links to banners hosted elsewhere have no file and are left out. 404 when nothing matches.
POST /api/v1/campaigns/{id}/banners
Upload creatives and backup images, as multipart/form-data:
| Field | What |
|---|---|
banners[] | HTML5 banner ZIPs, one banner per ZIP (a ZIP with several index.html files side by side is refused). The size comes from <meta name="ad.size"> or a 300x250 token in the file or folder name. |
media[] | Image and video creatives. |
mediaMeta | JSON [{ "name": "intro.mp4", "width": 1080, "height": 1920 }], for media whose size can't be read from the name. |
backups[] | Backup (fallback) images, matched to a banner by the size in the filename (300x250.jpg), or by the banner id when one size has several banners. |
stagedZips, preUploadedMedia | JSON lists of large files already uploaded through /upload-urls (below). |
expectedRevision | Optional. Uploads are additive, so a concurrent change is merged automatically; you rarely need this. |
A creative with the same id as an existing banner (same size and file name) replaces it as a new version: its group, order and backup image stay, and the client sees the new version. Any other field is refused with 400.
curl -X POST https://previewer.agency/api/v1/campaigns/42/banners \
-H "Authorization: Bearer $PREVIEWER_TOKEN" \
-F "banners[]=@dist/300x250.zip" \
-F "banners[]=@dist/728x90.zip" \
-F "backups[]=@dist/300x250.jpg"Response: the ids of what was uploaded, and the campaign as GET /campaigns/{id} returns it.
{ "uploaded": ["300x250-spring-300x250", "728x90-spring-728x90"], "campaign": { "id": 42, "…": "…" } }The account's storage limit applies; past it the upload is refused with 400 and a message.
DELETE /api/v1/campaigns/{id}/banners/{bannerId} (Manage)
Remove one banner with its backup image. Response: { "removed": "300x250-300x250", "campaign": … }.
PATCH /api/v1/campaigns/{id}/banners/{bannerId} (Manage)
Change how one banner appears on the preview. Send one or both:
{ "hidden": true }takes it off your client's page (it stays in the campaign and can't be approved while hidden);falseputs it back.{ "group": "Dutch" }puts it under that group, which is made if it doesn't exist;nulltakes it out of its group.
Response: { "campaign": … }. A banner's approval can't be changed here.
POST /api/v1/campaigns/{id}/banners/{bannerId}/backup (Upload)
Generate the backup image of one HTML5 banner: Previewer plays it to its end frame and saves a JPG within the size limit, as Generate backup in the admin does. No body.
{ "banner": "300x250-spring-300x250", "generated": true, "backupSizeBytes": 41280, "campaign": { "id": 42, "…": "…" } }It answers when the image is saved, which takes about as long as the banner plays plus a few seconds; allow two minutes. Do several banners one after another, not at the same time. generated is false when someone uploaded a backup while this one was rendering: that one is kept. 409 means the banner itself was replaced meanwhile; ask again. Images, videos and links get 400.
POST /api/v1/campaigns/{id}/upload-urls
One request can carry about 4 MB (a Vercel limit). For bigger files, ask for upload targets first, PUT each file there, then reference them in POST /banners.
{ "kind": "zip", "files": [{ "name": "970x250.zip", "size": 8123456 }] }kind is zip (HTML5 ZIPs up to 120 MB) or media (images and videos up to 200 MB; include contentType, and width/height for videos). The response:
{
"supabaseUrl": "https://….supabase.co",
"supabaseAnonKey": "…",
"bucket": "banners",
"uploads": [{ "name": "970x250.zip", "key": "assets/campaigns/42/staging/…", "token": "…" }]
}PUT each file to {supabaseUrl}/storage/v1/object/upload/sign/{bucket}/{key}?token={token} with the headers apikey: {supabaseAnonKey}, Authorization: Bearer {supabaseAnonKey} and the file's content-type, and the file as the body. Then:
- for ZIPs, send
stagedZips=[{ "key": "…", "name": "970x250.zip" }]toPOST /banners; - for media, send
preUploadedMedia= theuploadsentries (they carrybannerId,widthandheight).
Staged ZIPs are read and deleted by that upload. Register what you upload within a day: a file you uploaded and never registered counts towards the account's storage until it is removed, a day or so later.
Signing in a tool (previewer login)
For a tool that runs on someone's computer, instead of pasting a token:
- Make a token yourself:
pvw_+ 32 random bytes, base64url. POST /api/v1/cli-loginwith{ "tokenHash": "<sha256 hex of the token>", "tokenHint": "<its last 4 characters>", "clientName": "dave@MacBook" }. No token needed. You get{ "requestId", "userCode": "ABCD-EFGH", "verifyPath": "/admin/cli-login", "expiresAt" }.- Show the code and open
{site}{verifyPath}. The person signs in if needed, types the code and approves. The code is never part of the link, so a link someone sends can't be used to approve their sign-in, and the person gets an email about every terminal that signs in as them. - Poll
GET /api/v1/cli-login?request=<requestId>withAuthorization: Bearer <your token>every couple of seconds:{ "status": "pending" | "approved" | "denied" | "expired" }. A request lives 10 minutes. - Once approved, the token works like any other. The token never travels to the server in clear until you use it.
Starting a login is limited to 10 per 10 minutes per network.
Large files PUT to an upload target can't overwrite one that is already there: each target is a new file, used once.
Stability
Fields may be added to these responses; existing ones are not renamed or removed within v1.