# Listings API

Push your clipping, UGC, logo and music campaigns into ClippingAlpha with one PUT per listing. Quickstart with curl, API keys, the reference, examples and test mode.

As of 15:45 UTC on 18 Nov 2026. Page: https://clippingalpha.com/developers

Last updated 17 November 2026

Push your campaigns into ClippingAlpha, one PUT per listing. We read and score each one, and your join link brings clippers to you.

## Quickstart

- Turn on Developer mode in your profile and add your platform with its domain.
- Prove the domain with the DNS record or the file the page gives you. An admin then approves the platform once.
- Make a test key. Its listings are previews only you and our admins see, so try anything.
- Send a listing with the command below, then read it back to see its page, its analysis and any problem found.

```
curl -X PUT https://clippingalpha.com/api/v1/listings/podcast-ep-212 \
  -H "Authorization: Bearer ca_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme Podcast Clipping",
    "brand": {
      "name": "Acme Podcast",
      "site": "https://acmepodcast.example"
    },
    "type": "clipping",
    "pay": {
      "model": "per_1k",
      "ratePer1k": 1.5,
      "maxPerClip": 500,
      "minViews": 10000
    },
    "budget": {
      "total": 5000,
      "left": 5000
    },
    "apps": [
      "tiktok",
      "instagram",
      "youtube"
    ],
    "joinUrl": "https://yourplatform.example/campaigns/podcast-ep-212",
    "brief": "Cut the strongest moments of episode 212 into vertical clips. Hook in the first 3 seconds.",
    "rules": {
      "dos": [
        "Burn in captions"
      ],
      "donts": [
        "No other podcast'\''s audio"
      ],
      "requiredTags": [
        "#acmepodcast"
      ]
    },
    "assets": [
      {
        "url": "https://drive.example/acme/ep-212",
        "kind": "footage",
        "label": "Episode 212, full video"
      }
    ],
    "endsAt": "2026-12-31T23:59:00Z"
  }'
```

```
curl https://clippingalpha.com/api/v1/listings/podcast-ep-212 \
  -H "Authorization: Bearer ca_test_..."
```

## Authentication

Every request sends your key as a bearer token. Keys start ca\_live\_ or ca\_test\_, are shown once when made, and only their hash is kept. Revoke a key in Developer mode and it stops at once.

```
Authorization: Bearer ca_live_...
```

- **listings:write**: Create, replace and change listings.
- **listings:read**: List and read your listings.
- **Rate limit**: 300 requests a minute for each key. A body is 512 KB at most.
- **Base URL**: https://clippingalpha.com/api/v1

## Reference

### PUT /listings/{externalId}

Creates or replaces a listing by your own id (letters, digits and . \_ : -, 120 at most). The same body again changes nothing. 201 when created, 200 after.

- **title**: **Required.**text, 300 at most. The campaign's name as creators see it.
- **brand**: **Required.**object. name, and optional logoUrl and site (https links).
- **type**: **Required.**clipping, ugc, logo or music. clipping: clips cut from footage the campaign gives. ugc: original videos. logo: any video with the brand's logo. music: edits that use the track.
- **pay**: **Required.**object. model per\_1k, flat or per\_1k\_plus\_flat, with ratePer1k and flatPerPost as the model needs, and optional currency (USD), maxPerClip, minViews and feePct.
- **apps**: **Required.**list, 1 to 10. Where posts go: tiktok, instagram, youtube, x, facebook, twitch, kick, threads, snapchat, kwai.
- **joinUrl**: **Required.**https link. Where a creator joins the campaign on your platform.
- **budget**: object. total and left. Left is never more than the total.
- **requiresApplication**: true or false. A creator applies and is accepted before posting.
- **brief**: text, 200,000 at most. The brief in plain text or Markdown. Every word of it is read.
- **rules**: object. dos, donts, requiredTags, minFollowers, minDurationSec, maxPostsPerAccount and maxPostsPerDay.
- **assets**: list, 150 at most. Each a url with a kind (footage, file, brief, logo, link) and a label. Footage is what clipping campaigns are cut from.
- **sound**: object. name or url (TikTok, Instagram, YouTube or Spotify), and required when every post must use it.
- **examples**: list, 10 at most. Public posts on TikTok, Instagram, YouTube or X that show what you want.
- **audience**: object. countries whose views count, the posts' language and the share of viewers that must be there.
- **coverUrl**: https link. The campaign's picture.
- **startsAt**: date and time. When it opens, ISO 8601. A listing that starts later shows from then.
- **endsAt**: date and time. When it closes, ISO 8601, after startsAt.
- **state**: live, paused or ended. live unless you say otherwise.
- **regulatedCategory**: one word. gambling, prediction\_markets, crypto\_trading, adult, alcohol, tobacco\_vape, weight\_loss\_drugs, political, health\_products or weapons. The campaign shows as 18+.

### PATCH /listings/{externalId}

Changes what moves most, one field or several, without sending the whole listing.

- **state**: live, paused or ended. Pause or end the campaign.
- **budgetLeft**: number. What is left of the budget now.
- **budgetTotal**: number. The whole budget.
- **ratePer1k**: number. The new pay per 1,000 views.
- **flatPerPost**: number. The new pay a post.
- **endsAt**: date and time. The new end.

```
curl -X PATCH https://clippingalpha.com/api/v1/listings/podcast-ep-212 \
  -H "Authorization: Bearer ca_test_..." \
  -H "Content-Type: application/json" \
  -d '{"budgetLeft": 3200}'
```

### GET /listings/{externalId}

Where a listing stands: its page once shown, its Alpha Score once scored, the analysis state (queued, linking, analysing, scored or refused) and the problems found.

### GET /listings

Your listings in the key's mode, newest first, 50 a page. Send nextCursor as cursor for the next page.

```
curl "https://clippingalpha.com/api/v1/listings?limit=50" \
  -H "Authorization: Bearer ca_test_..."
```

### Errors

An error answers with a stable word in error, a sentence in message, and for invalid the fields that failed.

- **401 unauthorized**: No key, or a key that is not one, or revoked.
- **403 forbidden**: The key lacks the scope the route needs.
- **404 not\_found**: No listing with that id for this key's mode.
- **413 too\_large**: A body over 512 KB.
- **422 invalid**: A field failed. fields names each one with its path.
- **429 rate\_limited**: Over 300 requests a minute for the key. Wait for retry-after.

The whole API as OpenAPI 3.1: /api/v1/openapi.json

## Examples

One listing of each campaign type. Clipping gives the footage to cut, UGC asks for original videos, Logo for any video with the logo, Music for edits that use the track.

```
curl -X PUT https://clippingalpha.com/api/v1/listings/podcast-ep-212 \
  -H "Authorization: Bearer ca_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Acme Podcast Clipping",
    "brand": {
      "name": "Acme Podcast",
      "site": "https://acmepodcast.example"
    },
    "type": "clipping",
    "pay": {
      "model": "per_1k",
      "ratePer1k": 1.5,
      "maxPerClip": 500,
      "minViews": 10000
    },
    "budget": {
      "total": 5000,
      "left": 5000
    },
    "apps": [
      "tiktok",
      "instagram",
      "youtube"
    ],
    "joinUrl": "https://yourplatform.example/campaigns/podcast-ep-212",
    "brief": "Cut the strongest moments of episode 212 into vertical clips. Hook in the first 3 seconds.",
    "rules": {
      "dos": [
        "Burn in captions"
      ],
      "donts": [
        "No other podcast'\''s audio"
      ],
      "requiredTags": [
        "#acmepodcast"
      ]
    },
    "assets": [
      {
        "url": "https://drive.example/acme/ep-212",
        "kind": "footage",
        "label": "Episode 212, full video"
      }
    ],
    "endsAt": "2026-12-31T23:59:00Z"
  }'
```

## Test mode

- A test key's listings are previews: only your platform's members and our admins open them, and they are on no list, search, sitemap or feed.
- They are read and scored like live ones, so GET shows the analysis and problems you would get live.
- Test and live ids never meet: the same id under a test key and a live key are two listings.
- Until an admin approves your platform, live listings are previews too. They show once it is approved.

## Changelog

- **1.0.0, 17 November 2026**: First release: create, replace, change and read listings, live and test keys, the OpenAPI document.
