☰ Menu

Reference

API reference

Every endpoint of the Lokki REST API. This page and the OpenAPI document are generated from the same source, so they never drift.

Base URL

https://uselokki.com/api/v1

Auth

Authorization: Bearer lk_live_…

OpenAPI 3.1.0

/api/v1/openapi.json ↗

Import into Postman, Insomnia or a code generator.

Workspace#

Who you are, the brand kit, markets and connected TikTok accounts.

GET/api/v1/me#

Current workspace and key

Returns the workspace the key belongs to and the key's scopes. Use it to check a key works.

Responses

200Workspace and auth infoMe

200 response
{
  "workspace": {
    "id": "org_Ab12Cd34Ef56Gh",
    "name": "Wildcamp Co.",
    "slug": "wildcamp-co",
    "plan": "trial"
  },
  "auth": {
    "type": "api_key",
    "key": {
      "id": "key_Zx81Lq2Mw0",
      "name": "CMS integration",
      "prefix": "lk_live_AbCd",
      "last_used_at": 1795000000000
    },
    "scopes": [
      "posts:read",
      "posts:write",
      "assets:write",
      "templates:read",
      "templates:write",
      "markets:read",
      "approvals:write",
      "analytics:read",
      "webhooks:write"
    ]
  },
  "rate_limit": {
    "limit": 120,
    "window_seconds": 60
  }
}

Errors: 401 429 — see Errors.

GET/api/v1/brand#

Get the brand kit

scope templates:read

Parameters

brand_idquerystringDefaults to the first brand

Responses

200BrandBrand

Errors: 401 403 429 — see Errors.

PATCH/api/v1/brand#

Update the brand kit

scope templates:write

Colours and fonts feed the brand.* tokens in templates; tone, do's/don'ts, glossary and forbidden words steer the localizer. Admin role for session users.

Parameters

brand_idquerystring

Request body · application/json

FieldTypeDescription
namestringmin length 1
websitestring | null
tonestring | null
dosstring[]
dontsstring[]
forbidden_wordsstring[]Block approval when any slot or caption contains one
glossaryobject[]Terms never translated (keep) or with fixed translations per language
hashtagsstring[]
colorsobjectMerged over the current colours; used by brand.* tokens
fontsobjectFont families for brand.heading / brand.body
logo_asset_idstring | null
Example
{
  "colors": {
    "primary": "#FF7A3D"
  },
  "fonts": {
    "heading": "Acme Sans",
    "body": "Inter"
  },
  "forbidden_words": [
    "cheapest"
  ]
}

Responses

200Updated brandBrand

Errors: 401 403 400 429 — see Errors.

GET/api/v1/markets#

List markets

scope markets:read

Responses

200Markets

200 response
{
  "data": [
    {
      "id": "mkt_de4Gh7Ns2Kd",
      "brand_id": "brd_Kd8sL2pQw1",
      "name": "Germany",
      "country": "DE",
      "language": "de",
      "currency": "EUR",
      "timezone": "Europe/Berlin",
      "notes": "Use 'du'.",
      "offers": [
        {
          "title": "Herbst-Angebot",
          "text": "15% off stays in October"
        }
      ],
      "hashtags": [
        "glampingdeutschland"
      ],
      "posting_times": [
        "12:00",
        "19:00"
      ],
      "daily_post_cap": 3,
      "boost_monthly_budget": 500,
      "boost_daily_cap": 25,
      "auto_submit": true,
      "flag": "🇩🇪",
      "created_at": 1795000000000,
      "account": {
        "id": "acc_Wq81Lp0sZt3",
        "username": "wildcamp.de",
        "status": "connected"
      }
    }
  ]
}

Errors: 401 403 429 — see Errors.

POST/api/v1/markets#

Create a market

scope templates:write

A market = one country/language/account. Requires the admin role for session users.

Request body · application/json

FieldTypeDescription
namerequiredstringmin length 1
countryrequiredstringpattern ^[A-Za-z]{2}$
languagerequiredstringpattern ^[a-z]{2}(-[A-Z]{2})?$
currencyrequiredstringpattern ^[A-Za-z]{3}$
brand_idstring
timezonestringIANA zone, default Europe/Amsterdam
notesstring | nullLocal context for the localizer
offersobject[]Approved prices/offers; the AI never invents these
hashtagsstring[] | string
posting_timesstring[]Local times like "18:00"
daily_post_capintegermin 0 · max 15
boost_monthly_budgetnumbermin 0
boost_daily_capnumbermin 0
auto_submitboolean
flagstring | null
Example
{
  "name": "Germany",
  "country": "DE",
  "language": "de",
  "currency": "EUR",
  "timezone": "Europe/Berlin",
  "posting_times": [
    "12:00",
    "19:00"
  ]
}

Responses

201Created marketMarket

201 response
{
  "id": "mkt_de4Gh7Ns2Kd",
  "brand_id": "brd_Kd8sL2pQw1",
  "name": "Germany",
  "country": "DE",
  "language": "de",
  "currency": "EUR",
  "timezone": "Europe/Berlin",
  "notes": "Use 'du'.",
  "offers": [
    {
      "title": "Herbst-Angebot",
      "text": "15% off stays in October"
    }
  ],
  "hashtags": [
    "glampingdeutschland"
  ],
  "posting_times": [
    "12:00",
    "19:00"
  ],
  "daily_post_cap": 3,
  "boost_monthly_budget": 500,
  "boost_daily_cap": 25,
  "auto_submit": true,
  "flag": "🇩🇪",
  "created_at": 1795000000000,
  "account": {
    "id": "acc_Wq81Lp0sZt3",
    "username": "wildcamp.de",
    "status": "connected"
  }
}

Errors: 401 403 400 429 — see Errors.

GET/api/v1/markets/{id}#

Get a market

scope markets:read

Parameters

idrequiredpathstringMarket id

Responses

200MarketMarket

200 response
{
  "id": "mkt_de4Gh7Ns2Kd",
  "brand_id": "brd_Kd8sL2pQw1",
  "name": "Germany",
  "country": "DE",
  "language": "de",
  "currency": "EUR",
  "timezone": "Europe/Berlin",
  "notes": "Use 'du'.",
  "offers": [
    {
      "title": "Herbst-Angebot",
      "text": "15% off stays in October"
    }
  ],
  "hashtags": [
    "glampingdeutschland"
  ],
  "posting_times": [
    "12:00",
    "19:00"
  ],
  "daily_post_cap": 3,
  "boost_monthly_budget": 500,
  "boost_daily_cap": 25,
  "auto_submit": true,
  "flag": "🇩🇪",
  "created_at": 1795000000000,
  "account": {
    "id": "acc_Wq81Lp0sZt3",
    "username": "wildcamp.de",
    "status": "connected"
  }
}

Errors: 401 403 404 429 — see Errors.

PATCH/api/v1/markets/{id}#

Update a market

scope templates:write

Parameters

idrequiredpathstringMarket id

Request body · application/json

FieldTypeDescription
namestringmin length 1
countrystringpattern ^[A-Za-z]{2}$
languagestringpattern ^[a-z]{2}(-[A-Z]{2})?$
currencystringpattern ^[A-Za-z]{3}$
brand_idstring
timezonestringIANA zone, default Europe/Amsterdam
notesstring | nullLocal context for the localizer
offersobject[]Approved prices/offers; the AI never invents these
hashtagsstring[] | string
posting_timesstring[]Local times like "18:00"
daily_post_capintegermin 0 · max 15
boost_monthly_budgetnumbermin 0
boost_daily_capnumbermin 0
auto_submitboolean
flagstring | null
Example
{
  "daily_post_cap": 2,
  "offers": [
    {
      "title": "Winter",
      "text": "20% off in January"
    }
  ]
}

Responses

200Updated marketMarket

Errors: 401 403 404 400 429 — see Errors.

DEL/api/v1/markets/{id}#

Delete a market

scope templates:write

Only markets without posts can be deleted.

Parameters

idrequiredpathstringMarket id

Responses

200Deleted

Errors: 401 403 404 429 — see Errors.

GET/api/v1/accounts#

List TikTok accounts

scope markets:read

Accounts are connected by a person in the dashboard (TikTok OAuth); the API can read them.

Responses

200Accounts

Errors: 401 403 429 — see Errors.

Templates#

Your video templates (JSON specs) and fonts.

GET/api/v1/templates#

List templates

scope templates:read

Parameters

include_archivedqueryboolean

Responses

200System templates and yours

Errors: 401 403 429 — see Errors.

POST/api/v1/templates#

Create a template

scope templates:write

Push your own template spec. See the Templates & fonts guide for the spec reference.

Request body · application/json

FieldTypeDescription
namerequiredstringmin length 1 · max length 120
descriptionstringmax length 1000
categorystringmax length 60
specrequiredTemplateSpec
▸Example (159 lines)
json
{
  "name": "Bold hook",
  "category": "custom",
  "spec": {
    "version": 1,
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "slots": [
      {
        "key": "hook",
        "type": "text",
        "label": "Hook",
        "required": true,
        "maxChars": 48,
        "hint": "Max 6 words, a question or a bold claim"
      },
      {
        "key": "body",
        "type": "text",
        "label": "Body",
        "maxChars": 120,
        "multiline": true
      },
      {
        "key": "cta",
        "type": "text",
        "label": "Call to action",
        "default": "Link in bio"
      },
      {
        "key": "bg",
        "type": "media",
        "label": "Background",
        "accept": [
          "image",
          "video"
        ],
        "required": true
      }
    ],
    "scenes": [
      {
        "id": "intro",
        "duration": 3,
        "background": {
          "type": "media",
          "slot": "bg",
          "fit": "cover",
          "kenBurns": true,
          "dim": 0.25
        },
        "layers": [
          {
            "id": "hook",
            "type": "text",
            "slot": "hook",
            "x": 0.08,
            "y": 0.3,
            "w": 0.76,
            "h": 0.25,
            "font": {
              "family": "brand.heading",
              "size": 110,
              "uppercase": true,
              "autoFit": true,
              "minSize": 64,
              "maxLines": 3
            },
            "color": "brand.text",
            "align": "center",
            "valign": "middle",
            "highlightColor": "brand.primary",
            "animation": {
              "in": "pop",
              "out": "fade"
            }
          }
        ]
      },
      {
        "id": "body",
        "duration": 4,
        "transition": "fade",
        "background": {
          "type": "media",
          "slot": "bg",
          "fit": "cover",
          "dim": 0.45
        },
        "layers": [
          {
            "id": "body",
            "type": "text",
            "slot": "body",
            "x": 0.08,
            "y": 0.4,
            "w": 0.76,
            "h": 0.3,
            "font": {
              "family": "brand.body",
              "size": 60,
              "weight": 600,
              "autoFit": true,
              "minSize": 40
            },
            "color": "#FFFFFF",
            "align": "center",
            "plate": {
              "color": "rgba(0,0,0,0.55)",
              "radius": 18,
              "padX": 24,
              "padY": 12,
              "mode": "lines"
            },
            "animation": {
              "in": "slide-up"
            }
          },
          {
            "id": "cta",
            "type": "text",
            "slot": "cta",
            "x": 0.15,
            "y": 0.72,
            "w": 0.6,
            "h": 0.07,
            "font": {
              "family": "brand.heading",
              "size": 54
            },
            "color": "#000000",
            "align": "center",
            "plate": {
              "color": "brand.secondary",
              "radius": 40,
              "padX": 32,
              "padY": 14
            },
            "start": 1.2,
            "animation": {
              "in": "zoom"
            }
          },
          {
            "id": "logo",
            "type": "image",
            "src": "brand.logo",
            "x": 0.4,
            "y": 0.1,
            "w": 0.2,
            "h": 0.08,
            "fit": "contain"
          }
        ]
      }
    ]
  }
}

Responses

201Created templateTemplate

▸201 response (167 lines)
json
{
  "id": "tpl_Lm2Kx8Qp0Z",
  "name": "Bold hook",
  "description": "Hook, body, CTA over a photo or clip",
  "category": "custom",
  "spec": {
    "version": 1,
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "slots": [
      {
        "key": "hook",
        "type": "text",
        "label": "Hook",
        "required": true,
        "maxChars": 48,
        "hint": "Max 6 words, a question or a bold claim"
      },
      {
        "key": "body",
        "type": "text",
        "label": "Body",
        "maxChars": 120,
        "multiline": true
      },
      {
        "key": "cta",
        "type": "text",
        "label": "Call to action",
        "default": "Link in bio"
      },
      {
        "key": "bg",
        "type": "media",
        "label": "Background",
        "accept": [
          "image",
          "video"
        ],
        "required": true
      }
    ],
    "scenes": [
      {
        "id": "intro",
        "duration": 3,
        "background": {
          "type": "media",
          "slot": "bg",
          "fit": "cover",
          "kenBurns": true,
          "dim": 0.25
        },
        "layers": [
          {
            "id": "hook",
            "type": "text",
            "slot": "hook",
            "x": 0.08,
            "y": 0.3,
            "w": 0.76,
            "h": 0.25,
            "font": {
              "family": "brand.heading",
              "size": 110,
              "uppercase": true,
              "autoFit": true,
              "minSize": 64,
              "maxLines": 3
            },
            "color": "brand.text",
            "align": "center",
            "valign": "middle",
            "highlightColor": "brand.primary",
            "animation": {
              "in": "pop",
              "out": "fade"
            }
          }
        ]
      },
      {
        "id": "body",
        "duration": 4,
        "transition": "fade",
        "background": {
          "type": "media",
          "slot": "bg",
          "fit": "cover",
          "dim": 0.45
        },
        "layers": [
          {
            "id": "body",
            "type": "text",
            "slot": "body",
            "x": 0.08,
            "y": 0.4,
            "w": 0.76,
            "h": 0.3,
            "font": {
              "family": "brand.body",
              "size": 60,
              "weight": 600,
              "autoFit": true,
              "minSize": 40
            },
            "color": "#FFFFFF",
            "align": "center",
            "plate": {
              "color": "rgba(0,0,0,0.55)",
              "radius": 18,
              "padX": 24,
              "padY": 12,
              "mode": "lines"
            },
            "animation": {
              "in": "slide-up"
            }
          },
          {
            "id": "cta",
            "type": "text",
            "slot": "cta",
            "x": 0.15,
            "y": 0.72,
            "w": 0.6,
            "h": 0.07,
            "font": {
              "family": "brand.heading",
              "size": 54
            },
            "color": "#000000",
            "align": "center",
            "plate": {
              "color": "brand.secondary",
              "radius": 40,
              "padX": 32,
              "padY": 14
            },
            "start": 1.2,
            "animation": {
              "in": "zoom"
            }
          },
          {
            "id": "logo",
            "type": "image",
            "src": "brand.logo",
            "x": 0.4,
            "y": 0.1,
            "w": 0.2,
            "h": 0.08,
            "fit": "contain"
          }
        ]
      }
    ]
  },
  "version": 1,
  "archived": false,
  "is_system": false,
  "thumbnail_url": null,
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 400 429 — see Errors.

GET/api/v1/templates/{id}#

Get a template

scope templates:read

Parameters

idrequiredpathstringTemplate id

Responses

200TemplateTemplate

▸200 response (167 lines)
json
{
  "id": "tpl_Lm2Kx8Qp0Z",
  "name": "Bold hook",
  "description": "Hook, body, CTA over a photo or clip",
  "category": "custom",
  "spec": {
    "version": 1,
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "slots": [
      {
        "key": "hook",
        "type": "text",
        "label": "Hook",
        "required": true,
        "maxChars": 48,
        "hint": "Max 6 words, a question or a bold claim"
      },
      {
        "key": "body",
        "type": "text",
        "label": "Body",
        "maxChars": 120,
        "multiline": true
      },
      {
        "key": "cta",
        "type": "text",
        "label": "Call to action",
        "default": "Link in bio"
      },
      {
        "key": "bg",
        "type": "media",
        "label": "Background",
        "accept": [
          "image",
          "video"
        ],
        "required": true
      }
    ],
    "scenes": [
      {
        "id": "intro",
        "duration": 3,
        "background": {
          "type": "media",
          "slot": "bg",
          "fit": "cover",
          "kenBurns": true,
          "dim": 0.25
        },
        "layers": [
          {
            "id": "hook",
            "type": "text",
            "slot": "hook",
            "x": 0.08,
            "y": 0.3,
            "w": 0.76,
            "h": 0.25,
            "font": {
              "family": "brand.heading",
              "size": 110,
              "uppercase": true,
              "autoFit": true,
              "minSize": 64,
              "maxLines": 3
            },
            "color": "brand.text",
            "align": "center",
            "valign": "middle",
            "highlightColor": "brand.primary",
            "animation": {
              "in": "pop",
              "out": "fade"
            }
          }
        ]
      },
      {
        "id": "body",
        "duration": 4,
        "transition": "fade",
        "background": {
          "type": "media",
          "slot": "bg",
          "fit": "cover",
          "dim": 0.45
        },
        "layers": [
          {
            "id": "body",
            "type": "text",
            "slot": "body",
            "x": 0.08,
            "y": 0.4,
            "w": 0.76,
            "h": 0.3,
            "font": {
              "family": "brand.body",
              "size": 60,
              "weight": 600,
              "autoFit": true,
              "minSize": 40
            },
            "color": "#FFFFFF",
            "align": "center",
            "plate": {
              "color": "rgba(0,0,0,0.55)",
              "radius": 18,
              "padX": 24,
              "padY": 12,
              "mode": "lines"
            },
            "animation": {
              "in": "slide-up"
            }
          },
          {
            "id": "cta",
            "type": "text",
            "slot": "cta",
            "x": 0.15,
            "y": 0.72,
            "w": 0.6,
            "h": 0.07,
            "font": {
              "family": "brand.heading",
              "size": 54
            },
            "color": "#000000",
            "align": "center",
            "plate": {
              "color": "brand.secondary",
              "radius": 40,
              "padX": 32,
              "padY": 14
            },
            "start": 1.2,
            "animation": {
              "in": "zoom"
            }
          },
          {
            "id": "logo",
            "type": "image",
            "src": "brand.logo",
            "x": 0.4,
            "y": 0.1,
            "w": 0.2,
            "h": 0.08,
            "fit": "contain"
          }
        ]
      }
    ]
  },
  "version": 1,
  "archived": false,
  "is_system": false,
  "thumbnail_url": null,
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 429 — see Errors.

PATCH/api/v1/templates/{id}#

Update a template

scope templates:write

System templates are read-only; duplicate them first. Changing the spec bumps version. Existing variants keep their render until edited.

Parameters

idrequiredpathstringTemplate id

Request body · application/json

FieldTypeDescription
namestringmin length 1 · max length 120
descriptionstringmax length 1000
categorystringmax length 60
specTemplateSpecReplacing the spec bumps the version
Example
{
  "name": "Bold hook v2"
}

Responses

200Updated templateTemplate

Errors: 401 403 404 400 429 — see Errors.

POST/api/v1/templates/{id}/duplicate#

Duplicate a template

scope templates:write

Parameters

idrequiredpathstringTemplate id

Request body · application/json

FieldTypeDescription
namestringmin length 1 · max length 120
Example
{
  "name": "Bold hook (DE)"
}

Responses

201The copyTemplate

Errors: 401 403 404 400 429 — see Errors.

GET/api/v1/fonts#

List fonts

scope templates:read

Built-in fonts plus the ones you uploaded.

Responses

200Fonts

Errors: 401 403 429 — see Errors.

POST/api/v1/fonts#

Upload a font

scope assets:write

Upload one file per weight/style. Family/weight/style are guessed from the filename (AcmeSans-BoldItalic.otf) unless given.

Request body · multipart/form-data

FieldTypeDescription
filerequiredstring.ttf, .otf, .woff or .woff2 (binary)binary
familystring
weightstring100..900
style"normal" | "italic"

Responses

201FontFont

201 response
{
  "id": "fnt_Bx82Lq0Pz1",
  "family": "Acme Sans",
  "weight": 700,
  "style": "normal",
  "source": "upload",
  "builtin": false,
  "url": "/api/fonts/fnt_Bx82Lq0Pz1/file",
  "created_at": 1795000000000
}

Errors: 401 403 400 429 — see Errors.

Assets#

Upload media or import it from a URL.

POST/api/v1/assets#

Upload or import media

scope assets:write

Send multipart/form-data with file, or JSON { url } to have Lokki download it. Max 500 MB.

Request body · multipart/form-data

FieldTypeDescription
filerequiredstringImage, video or audio (binary)binary

Request body · application/json

FieldTypeDescription
urlrequiredstringhttp(s) URL of an image, video or audio fileuri
filenamestring
Example
{
  "url": "https://cdn.example.com/photos/forest-dome.jpg"
}

Responses

201AssetAsset

201 response
{
  "id": "ast_Q2w8Lm4Kx0Pz",
  "kind": "image",
  "filename": "forest-dome.jpg",
  "mime": "image/jpeg",
  "size": 482113,
  "sha256": "9f2c…",
  "width": 1080,
  "height": 1920,
  "duration": null,
  "url": "/api/assets/ast_Q2w8Lm4Kx0Pz/file",
  "created_at": 1795000000000
}

Errors: 401 403 400 429 — see Errors.

GET/api/v1/assets/{id}#

Get asset metadata

scope posts:read

Parameters

idrequiredpathstringAsset id

Responses

200AssetAsset

200 response
{
  "id": "ast_Q2w8Lm4Kx0Pz",
  "kind": "image",
  "filename": "forest-dome.jpg",
  "mime": "image/jpeg",
  "size": 482113,
  "sha256": "9f2c…",
  "width": 1080,
  "height": 1920,
  "duration": null,
  "url": "/api/assets/ast_Q2w8Lm4Kx0Pz/file",
  "created_at": 1795000000000
}

Errors: 401 403 404 429 — see Errors.

Posts#

Create posts that fan out to one variant per market.

POST/api/v1/posts#

Create a post

scope posts:write

Creates a post and one variant per market. Each variant is localized (AI, your overrides, or the source text when the language matches / translate:false), rendered into the template, and submitted for approval.

media values may be an asset id or { "url": "https://…" } (imported first; needs assets:write).

markets accepts ids, language codes (de), country codes (DE) or ["all"].

Idempotency: when external_ref already exists the existing post is returned with HTTP 200 and "idempotent": true; new posts return 201.

Request body · application/json

FieldTypeDescription
template_idrequiredstringSystem template (tpl_sys_…) or one of yoursmin length 1
brand_idstringDefaults to the workspace's first brand
titlerequiredstringInternal title (not posted)min length 1 · max length 200
source_languagestringdefault "en" · pattern ^[a-z]{2}(-[A-Z]{2})?$
fieldsmap<string, string>Text slot key → source textdefault {}
mediamap<string, MediaRef>Media slot key → asset id or { url }
captionstringSource caption (localized per market)max length 2200
hashtagsstring[] | stringWithout #; market and brand hashtags are appended
briefstringExtra guidance for localization, e.g. "mention the autumn deal"max length 2000
marketsstring[] | stringMarket ids, language codes, country codes, or ["all"] (default, unless locations is given)
locationsstring[] | stringLocation ids, slugs or external_ids, "all", or a market id/language/country (= its active locations). One version per location, posted to the location's own account; locations of one market are localized once
overridesmap<string, VariantOverride>Keyed by market id, language or country code, or location id/slug/external_id
translatebooleanfalse = never call the AI; markets without an override get the source text
ai_generatedbooleanSets TikTok's AI-generated content label
brand_organicboolean"Promotional content" disclosure (default off)
schedule_atnumber | string | nullISO 8601 date-time (e.g. 2026-12-01T18:00:00+01:00), Unix milliseconds, or null
external_refstringYour id (CMS, PIM…). Idempotency key: re-sending returns the existing postmax length 200
auto_submitbooleanSubmit for approval automatically once rendered (default: market setting)
Example — AI localization for all markets
{
  "template_id": "tpl_sys_bold_hook",
  "title": "Autumn midweek deal",
  "source_language": "en",
  "fields": {
    "hook": "Wake up *inside* the forest",
    "body": "Midweek stays, three nights for the price of two.",
    "cta": "Book in bio"
  },
  "media": {
    "bg": {
      "url": "https://cdn.example.com/photos/forest-dome.jpg"
    }
  },
  "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
  "hashtags": [
    "autumn",
    "midweek"
  ],
  "markets": [
    "all"
  ],
  "external_ref": "cms-4711"
}
Example — Your own translations
{
  "template_id": "tpl_sys_bold_hook",
  "title": "Autumn midweek deal (own translations)",
  "source_language": "en",
  "fields": {
    "hook": "Wake up *inside* the forest",
    "body": "Three nights for the price of two.",
    "cta": "Book in bio"
  },
  "media": {
    "bg": "ast_Q2w8Lm4Kx0Pz"
  },
  "caption": "Three nights in the forest, pay for two.",
  "markets": [
    "nl",
    "de",
    "gb"
  ],
  "overrides": {
    "nl": {
      "fields": {
        "hook": "Word wakker *midden* in het bos",
        "body": "Drie nachten, betaal er twee.",
        "cta": "Boek via bio"
      },
      "caption": "Drie nachten in het bos, betaal er twee."
    },
    "de": {
      "fields": {
        "hook": "Wach *mitten* im Wald auf",
        "body": "Drei Nächte zum Preis von zwei.",
        "cta": "Link in Bio"
      },
      "caption": "Drei Nächte im Wald, zahl nur zwei."
    }
  },
  "translate": false,
  "external_ref": "cms-4712"
}

Responses

200Already existed (same external_ref)CreatePostResponse

▸200 response (216 lines)
json
{
  "idempotent": true,
  "post": {
    "id": "post_7f3k2Qx9Lm2Ab",
    "title": "Autumn midweek deal",
    "template_id": "tpl_sys_bold_hook",
    "brand_id": "brd_Kd8sL2pQw1",
    "source_language": "en",
    "fields": {
      "hook": "Wake up *inside* the forest",
      "body": "Midweek stays, three nights for the price of two.",
      "cta": "Book in bio"
    },
    "media": {
      "bg": "ast_Q2w8Lm4Kx0Pz"
    },
    "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
    "hashtags": [
      "autumn",
      "midweek"
    ],
    "brief": null,
    "status": "active",
    "external_ref": "cms-4711",
    "created_via": "api",
    "ai_generated": false,
    "brand_organic": false,
    "schedule_at": null,
    "created_at": 1795000000000,
    "updated_at": 1795000000000,
    "summary": {
      "markets": 3,
      "by_status": {
        "localizing": 2,
        "rendering": 1
      }
    },
    "metrics": {
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0
    },
    "variants": [
      {
        "id": "var_nl9Fk2LmQx81",
        "post_id": "post_7f3k2Qx9Lm2Ab",
        "market_id": "mkt_nl4Gh7Ns2Kd",
        "market": {
          "id": "mkt_nl4Gh7Ns2Kd",
          "name": "Netherlands",
          "country": "NL",
          "language": "nl",
          "flag": "🇳🇱"
        },
        "account_id": "acc_Wq81Lp0sZt3",
        "language": "nl",
        "status": "localizing",
        "status_label": "Localizing",
        "localized_by": null,
        "fields": {
          "hook": "…",
          "body": "…",
          "cta": "…"
        },
        "caption": "…",
        "hashtags": [
          "wildcamp",
          "glamping"
        ],
        "checks": [],
        "edited": false,
        "scheduled_at": null,
        "approval_id": null,
        "post_url": null,
        "tiktok_video_id": null,
        "published_at": null,
        "error": null,
        "render_error": null,
        "preview_url": null,
        "video_url": null,
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0,
          "avg_watch_time": null,
          "baseline_ratio": null,
          "is_winner": false,
          "synced_at": null
        },
        "links": {
          "self": "/api/v1/variants/var_nl9Fk2LmQx81",
          "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        },
        "created_at": 1795000000000,
        "updated_at": 1795000000000
      },
      {
        "id": "var_de9Fk2LmQx81",
        "post_id": "post_7f3k2Qx9Lm2Ab",
        "market_id": "mkt_de4Gh7Ns2Kd",
        "market": {
          "id": "mkt_de4Gh7Ns2Kd",
          "name": "Germany",
          "country": "DE",
          "language": "de",
          "flag": "🇩🇪"
        },
        "account_id": "acc_Wq81Lp0sZt3",
        "language": "de",
        "status": "localizing",
        "status_label": "Localizing",
        "localized_by": null,
        "fields": {
          "hook": "…",
          "body": "…",
          "cta": "…"
        },
        "caption": "…",
        "hashtags": [
          "wildcamp",
          "glamping"
        ],
        "checks": [],
        "edited": false,
        "scheduled_at": null,
        "approval_id": null,
        "post_url": null,
        "tiktok_video_id": null,
        "published_at": null,
        "error": null,
        "render_error": null,
        "preview_url": null,
        "video_url": null,
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0,
          "avg_watch_time": null,
          "baseline_ratio": null,
          "is_winner": false,
          "synced_at": null
        },
        "links": {
          "self": "/api/v1/variants/var_de9Fk2LmQx81",
          "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        },
        "created_at": 1795000000000,
        "updated_at": 1795000000000
      },
      {
        "id": "var_gb9Fk2LmQx81",
        "post_id": "post_7f3k2Qx9Lm2Ab",
        "market_id": "mkt_gb4Gh7Ns2Kd",
        "market": {
          "id": "mkt_gb4Gh7Ns2Kd",
          "name": "United Kingdom",
          "country": "GB",
          "language": "en",
          "flag": "🇬🇧"
        },
        "account_id": "acc_Wq81Lp0sZt3",
        "language": "en",
        "status": "rendering",
        "status_label": "Rendering",
        "localized_by": "source",
        "fields": {
          "hook": "Wake up *inside* the forest",
          "body": "Midweek stays, three nights for the price of two.",
          "cta": "Book in bio"
        },
        "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
        "hashtags": [
          "wildcamp",
          "glamping"
        ],
        "checks": [],
        "edited": false,
        "scheduled_at": null,
        "approval_id": null,
        "post_url": null,
        "tiktok_video_id": null,
        "published_at": null,
        "error": null,
        "render_error": null,
        "preview_url": null,
        "video_url": null,
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0,
          "avg_watch_time": null,
          "baseline_ratio": null,
          "is_winner": false,
          "synced_at": null
        },
        "links": {
          "self": "/api/v1/variants/var_gb9Fk2LmQx81",
          "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        },
        "created_at": 1795000000000,
        "updated_at": 1795000000000
      }
    ],
    "links": {
      "self": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
      "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
    }
  }
}

201CreatedCreatePostResponse

▸201 response (216 lines)
json
{
  "idempotent": false,
  "post": {
    "id": "post_7f3k2Qx9Lm2Ab",
    "title": "Autumn midweek deal",
    "template_id": "tpl_sys_bold_hook",
    "brand_id": "brd_Kd8sL2pQw1",
    "source_language": "en",
    "fields": {
      "hook": "Wake up *inside* the forest",
      "body": "Midweek stays, three nights for the price of two.",
      "cta": "Book in bio"
    },
    "media": {
      "bg": "ast_Q2w8Lm4Kx0Pz"
    },
    "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
    "hashtags": [
      "autumn",
      "midweek"
    ],
    "brief": null,
    "status": "active",
    "external_ref": "cms-4711",
    "created_via": "api",
    "ai_generated": false,
    "brand_organic": false,
    "schedule_at": null,
    "created_at": 1795000000000,
    "updated_at": 1795000000000,
    "summary": {
      "markets": 3,
      "by_status": {
        "localizing": 2,
        "rendering": 1
      }
    },
    "metrics": {
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0
    },
    "variants": [
      {
        "id": "var_nl9Fk2LmQx81",
        "post_id": "post_7f3k2Qx9Lm2Ab",
        "market_id": "mkt_nl4Gh7Ns2Kd",
        "market": {
          "id": "mkt_nl4Gh7Ns2Kd",
          "name": "Netherlands",
          "country": "NL",
          "language": "nl",
          "flag": "🇳🇱"
        },
        "account_id": "acc_Wq81Lp0sZt3",
        "language": "nl",
        "status": "localizing",
        "status_label": "Localizing",
        "localized_by": null,
        "fields": {
          "hook": "…",
          "body": "…",
          "cta": "…"
        },
        "caption": "…",
        "hashtags": [
          "wildcamp",
          "glamping"
        ],
        "checks": [],
        "edited": false,
        "scheduled_at": null,
        "approval_id": null,
        "post_url": null,
        "tiktok_video_id": null,
        "published_at": null,
        "error": null,
        "render_error": null,
        "preview_url": null,
        "video_url": null,
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0,
          "avg_watch_time": null,
          "baseline_ratio": null,
          "is_winner": false,
          "synced_at": null
        },
        "links": {
          "self": "/api/v1/variants/var_nl9Fk2LmQx81",
          "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        },
        "created_at": 1795000000000,
        "updated_at": 1795000000000
      },
      {
        "id": "var_de9Fk2LmQx81",
        "post_id": "post_7f3k2Qx9Lm2Ab",
        "market_id": "mkt_de4Gh7Ns2Kd",
        "market": {
          "id": "mkt_de4Gh7Ns2Kd",
          "name": "Germany",
          "country": "DE",
          "language": "de",
          "flag": "🇩🇪"
        },
        "account_id": "acc_Wq81Lp0sZt3",
        "language": "de",
        "status": "localizing",
        "status_label": "Localizing",
        "localized_by": null,
        "fields": {
          "hook": "…",
          "body": "…",
          "cta": "…"
        },
        "caption": "…",
        "hashtags": [
          "wildcamp",
          "glamping"
        ],
        "checks": [],
        "edited": false,
        "scheduled_at": null,
        "approval_id": null,
        "post_url": null,
        "tiktok_video_id": null,
        "published_at": null,
        "error": null,
        "render_error": null,
        "preview_url": null,
        "video_url": null,
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0,
          "avg_watch_time": null,
          "baseline_ratio": null,
          "is_winner": false,
          "synced_at": null
        },
        "links": {
          "self": "/api/v1/variants/var_de9Fk2LmQx81",
          "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        },
        "created_at": 1795000000000,
        "updated_at": 1795000000000
      },
      {
        "id": "var_gb9Fk2LmQx81",
        "post_id": "post_7f3k2Qx9Lm2Ab",
        "market_id": "mkt_gb4Gh7Ns2Kd",
        "market": {
          "id": "mkt_gb4Gh7Ns2Kd",
          "name": "United Kingdom",
          "country": "GB",
          "language": "en",
          "flag": "🇬🇧"
        },
        "account_id": "acc_Wq81Lp0sZt3",
        "language": "en",
        "status": "rendering",
        "status_label": "Rendering",
        "localized_by": "source",
        "fields": {
          "hook": "Wake up *inside* the forest",
          "body": "Midweek stays, three nights for the price of two.",
          "cta": "Book in bio"
        },
        "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
        "hashtags": [
          "wildcamp",
          "glamping"
        ],
        "checks": [],
        "edited": false,
        "scheduled_at": null,
        "approval_id": null,
        "post_url": null,
        "tiktok_video_id": null,
        "published_at": null,
        "error": null,
        "render_error": null,
        "preview_url": null,
        "video_url": null,
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0,
          "avg_watch_time": null,
          "baseline_ratio": null,
          "is_winner": false,
          "synced_at": null
        },
        "links": {
          "self": "/api/v1/variants/var_gb9Fk2LmQx81",
          "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        },
        "created_at": 1795000000000,
        "updated_at": 1795000000000
      }
    ],
    "links": {
      "self": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
      "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
    }
  }
}

Errors: 401 403 400 429 — see Errors.

POST/api/v1/posts/bulk#

Create up to 100 posts

scope posts:write

Each item is processed independently (same rules as POST /posts). The response always has HTTP 200 with a result per item.

Request body · application/json

FieldTypeDescription
postsrequiredany[]Up to 100 CreatePostRequest objects; each is validated separatelymin 1 items · max 100 items
▸Example (67 lines)
json
{
  "posts": [
    {
      "template_id": "tpl_sys_bold_hook",
      "title": "Autumn midweek deal",
      "source_language": "en",
      "fields": {
        "hook": "Wake up *inside* the forest",
        "body": "Midweek stays, three nights for the price of two.",
        "cta": "Book in bio"
      },
      "media": {
        "bg": {
          "url": "https://cdn.example.com/photos/forest-dome.jpg"
        }
      },
      "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
      "hashtags": [
        "autumn",
        "midweek"
      ],
      "markets": [
        "all"
      ],
      "external_ref": "cms-4711"
    },
    {
      "template_id": "tpl_sys_bold_hook",
      "title": "Autumn midweek deal (own translations)",
      "source_language": "en",
      "fields": {
        "hook": "Wake up *inside* the forest",
        "body": "Three nights for the price of two.",
        "cta": "Book in bio"
      },
      "media": {
        "bg": "ast_Q2w8Lm4Kx0Pz"
      },
      "caption": "Three nights in the forest, pay for two.",
      "markets": [
        "nl",
        "de",
        "gb"
      ],
      "overrides": {
        "nl": {
          "fields": {
            "hook": "Word wakker *midden* in het bos",
            "body": "Drie nachten, betaal er twee.",
            "cta": "Boek via bio"
          },
          "caption": "Drie nachten in het bos, betaal er twee."
        },
        "de": {
          "fields": {
            "hook": "Wach *mitten* im Wald auf",
            "body": "Drei Nächte zum Preis von zwei.",
            "cta": "Link in Bio"
          },
          "caption": "Drei Nächte im Wald, zahl nur zwei."
        }
      },
      "translate": false,
      "external_ref": "cms-4712"
    }
  ]
}

Responses

200Per-item resultsBulkPostsResponse

▸200 response (448 lines)
json
{
  "summary": {
    "total": 2,
    "created": 1,
    "existing": 1,
    "failed": 0
  },
  "results": [
    {
      "index": 0,
      "status": 201,
      "ok": true,
      "idempotent": false,
      "post": {
        "id": "post_7f3k2Qx9Lm2Ab",
        "title": "Autumn midweek deal",
        "template_id": "tpl_sys_bold_hook",
        "brand_id": "brd_Kd8sL2pQw1",
        "source_language": "en",
        "fields": {
          "hook": "Wake up *inside* the forest",
          "body": "Midweek stays, three nights for the price of two.",
          "cta": "Book in bio"
        },
        "media": {
          "bg": "ast_Q2w8Lm4Kx0Pz"
        },
        "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
        "hashtags": [
          "autumn",
          "midweek"
        ],
        "brief": null,
        "status": "active",
        "external_ref": "cms-4711",
        "created_via": "api",
        "ai_generated": false,
        "brand_organic": false,
        "schedule_at": null,
        "created_at": 1795000000000,
        "updated_at": 1795000000000,
        "summary": {
          "markets": 3,
          "by_status": {
            "localizing": 2,
            "rendering": 1
          }
        },
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0
        },
        "variants": [
          {
            "id": "var_nl9Fk2LmQx81",
            "post_id": "post_7f3k2Qx9Lm2Ab",
            "market_id": "mkt_nl4Gh7Ns2Kd",
            "market": {
              "id": "mkt_nl4Gh7Ns2Kd",
              "name": "Netherlands",
              "country": "NL",
              "language": "nl",
              "flag": "🇳🇱"
            },
            "account_id": "acc_Wq81Lp0sZt3",
            "language": "nl",
            "status": "localizing",
            "status_label": "Localizing",
            "localized_by": null,
            "fields": {
              "hook": "…",
              "body": "…",
              "cta": "…"
            },
            "caption": "…",
            "hashtags": [
              "wildcamp",
              "glamping"
            ],
            "checks": [],
            "edited": false,
            "scheduled_at": null,
            "approval_id": null,
            "post_url": null,
            "tiktok_video_id": null,
            "published_at": null,
            "error": null,
            "render_error": null,
            "preview_url": null,
            "video_url": null,
            "metrics": {
              "views": 0,
              "likes": 0,
              "comments": 0,
              "shares": 0,
              "avg_watch_time": null,
              "baseline_ratio": null,
              "is_winner": false,
              "synced_at": null
            },
            "links": {
              "self": "/api/v1/variants/var_nl9Fk2LmQx81",
              "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
              "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
            },
            "created_at": 1795000000000,
            "updated_at": 1795000000000
          },
          {
            "id": "var_de9Fk2LmQx81",
            "post_id": "post_7f3k2Qx9Lm2Ab",
            "market_id": "mkt_de4Gh7Ns2Kd",
            "market": {
              "id": "mkt_de4Gh7Ns2Kd",
              "name": "Germany",
              "country": "DE",
              "language": "de",
              "flag": "🇩🇪"
            },
            "account_id": "acc_Wq81Lp0sZt3",
            "language": "de",
            "status": "localizing",
            "status_label": "Localizing",
            "localized_by": null,
            "fields": {
              "hook": "…",
              "body": "…",
              "cta": "…"
            },
            "caption": "…",
            "hashtags": [
              "wildcamp",
              "glamping"
            ],
            "checks": [],
            "edited": false,
            "scheduled_at": null,
            "approval_id": null,
            "post_url": null,
            "tiktok_video_id": null,
            "published_at": null,
            "error": null,
            "render_error": null,
            "preview_url": null,
            "video_url": null,
            "metrics": {
              "views": 0,
              "likes": 0,
              "comments": 0,
              "shares": 0,
              "avg_watch_time": null,
              "baseline_ratio": null,
              "is_winner": false,
              "synced_at": null
            },
            "links": {
              "self": "/api/v1/variants/var_de9Fk2LmQx81",
              "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
              "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
            },
            "created_at": 1795000000000,
            "updated_at": 1795000000000
          },
          {
            "id": "var_gb9Fk2LmQx81",
            "post_id": "post_7f3k2Qx9Lm2Ab",
            "market_id": "mkt_gb4Gh7Ns2Kd",
            "market": {
              "id": "mkt_gb4Gh7Ns2Kd",
              "name": "United Kingdom",
              "country": "GB",
              "language": "en",
              "flag": "🇬🇧"
            },
            "account_id": "acc_Wq81Lp0sZt3",
            "language": "en",
            "status": "rendering",
            "status_label": "Rendering",
            "localized_by": "source",
            "fields": {
              "hook": "Wake up *inside* the forest",
              "body": "Midweek stays, three nights for the price of two.",
              "cta": "Book in bio"
            },
            "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
            "hashtags": [
              "wildcamp",
              "glamping"
            ],
            "checks": [],
            "edited": false,
            "scheduled_at": null,
            "approval_id": null,
            "post_url": null,
            "tiktok_video_id": null,
            "published_at": null,
            "error": null,
            "render_error": null,
            "preview_url": null,
            "video_url": null,
            "metrics": {
              "views": 0,
              "likes": 0,
              "comments": 0,
              "shares": 0,
              "avg_watch_time": null,
              "baseline_ratio": null,
              "is_winner": false,
              "synced_at": null
            },
            "links": {
              "self": "/api/v1/variants/var_gb9Fk2LmQx81",
              "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
              "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
            },
            "created_at": 1795000000000,
            "updated_at": 1795000000000
          }
        ],
        "links": {
          "self": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        }
      }
    },
    {
      "index": 1,
      "status": 200,
      "ok": true,
      "idempotent": true,
      "post": {
        "id": "post_7f3k2Qx9Lm2Ab",
        "title": "Autumn midweek deal",
        "template_id": "tpl_sys_bold_hook",
        "brand_id": "brd_Kd8sL2pQw1",
        "source_language": "en",
        "fields": {
          "hook": "Wake up *inside* the forest",
          "body": "Midweek stays, three nights for the price of two.",
          "cta": "Book in bio"
        },
        "media": {
          "bg": "ast_Q2w8Lm4Kx0Pz"
        },
        "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
        "hashtags": [
          "autumn",
          "midweek"
        ],
        "brief": null,
        "status": "active",
        "external_ref": "cms-4711",
        "created_via": "api",
        "ai_generated": false,
        "brand_organic": false,
        "schedule_at": null,
        "created_at": 1795000000000,
        "updated_at": 1795000000000,
        "summary": {
          "markets": 3,
          "by_status": {
            "localizing": 2,
            "rendering": 1
          }
        },
        "metrics": {
          "views": 0,
          "likes": 0,
          "comments": 0,
          "shares": 0
        },
        "variants": [
          {
            "id": "var_nl9Fk2LmQx81",
            "post_id": "post_7f3k2Qx9Lm2Ab",
            "market_id": "mkt_nl4Gh7Ns2Kd",
            "market": {
              "id": "mkt_nl4Gh7Ns2Kd",
              "name": "Netherlands",
              "country": "NL",
              "language": "nl",
              "flag": "🇳🇱"
            },
            "account_id": "acc_Wq81Lp0sZt3",
            "language": "nl",
            "status": "localizing",
            "status_label": "Localizing",
            "localized_by": null,
            "fields": {
              "hook": "…",
              "body": "…",
              "cta": "…"
            },
            "caption": "…",
            "hashtags": [
              "wildcamp",
              "glamping"
            ],
            "checks": [],
            "edited": false,
            "scheduled_at": null,
            "approval_id": null,
            "post_url": null,
            "tiktok_video_id": null,
            "published_at": null,
            "error": null,
            "render_error": null,
            "preview_url": null,
            "video_url": null,
            "metrics": {
              "views": 0,
              "likes": 0,
              "comments": 0,
              "shares": 0,
              "avg_watch_time": null,
              "baseline_ratio": null,
              "is_winner": false,
              "synced_at": null
            },
            "links": {
              "self": "/api/v1/variants/var_nl9Fk2LmQx81",
              "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
              "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
            },
            "created_at": 1795000000000,
            "updated_at": 1795000000000
          },
          {
            "id": "var_de9Fk2LmQx81",
            "post_id": "post_7f3k2Qx9Lm2Ab",
            "market_id": "mkt_de4Gh7Ns2Kd",
            "market": {
              "id": "mkt_de4Gh7Ns2Kd",
              "name": "Germany",
              "country": "DE",
              "language": "de",
              "flag": "🇩🇪"
            },
            "account_id": "acc_Wq81Lp0sZt3",
            "language": "de",
            "status": "localizing",
            "status_label": "Localizing",
            "localized_by": null,
            "fields": {
              "hook": "…",
              "body": "…",
              "cta": "…"
            },
            "caption": "…",
            "hashtags": [
              "wildcamp",
              "glamping"
            ],
            "checks": [],
            "edited": false,
            "scheduled_at": null,
            "approval_id": null,
            "post_url": null,
            "tiktok_video_id": null,
            "published_at": null,
            "error": null,
            "render_error": null,
            "preview_url": null,
            "video_url": null,
            "metrics": {
              "views": 0,
              "likes": 0,
              "comments": 0,
              "shares": 0,
              "avg_watch_time": null,
              "baseline_ratio": null,
              "is_winner": false,
              "synced_at": null
            },
            "links": {
              "self": "/api/v1/variants/var_de9Fk2LmQx81",
              "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
              "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
            },
            "created_at": 1795000000000,
            "updated_at": 1795000000000
          },
          {
            "id": "var_gb9Fk2LmQx81",
            "post_id": "post_7f3k2Qx9Lm2Ab",
            "market_id": "mkt_gb4Gh7Ns2Kd",
            "market": {
              "id": "mkt_gb4Gh7Ns2Kd",
              "name": "United Kingdom",
              "country": "GB",
              "language": "en",
              "flag": "🇬🇧"
            },
            "account_id": "acc_Wq81Lp0sZt3",
            "language": "en",
            "status": "rendering",
            "status_label": "Rendering",
            "localized_by": "source",
            "fields": {
              "hook": "Wake up *inside* the forest",
              "body": "Midweek stays, three nights for the price of two.",
              "cta": "Book in bio"
            },
            "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
            "hashtags": [
              "wildcamp",
              "glamping"
            ],
            "checks": [],
            "edited": false,
            "scheduled_at": null,
            "approval_id": null,
            "post_url": null,
            "tiktok_video_id": null,
            "published_at": null,
            "error": null,
            "render_error": null,
            "preview_url": null,
            "video_url": null,
            "metrics": {
              "views": 0,
              "likes": 0,
              "comments": 0,
              "shares": 0,
              "avg_watch_time": null,
              "baseline_ratio": null,
              "is_winner": false,
              "synced_at": null
            },
            "links": {
              "self": "/api/v1/variants/var_gb9Fk2LmQx81",
              "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
              "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
            },
            "created_at": 1795000000000,
            "updated_at": 1795000000000
          }
        ],
        "links": {
          "self": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
          "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
        }
      }
    }
  ]
}

Errors: 401 403 400 429 — see Errors.

GET/api/v1/posts#

List posts

scope posts:read

Newest first. Paginate with cursor (preferred) or offset.

Parameters

limitqueryinteger1–100, default 25
cursorquerystringnext_cursor from the previous page
offsetqueryinteger
statusquery"localizing" | "rendering" | "rendered" | "pending_approval" | "approved" | "publishing" | "published" | "rejected" | "failed" | "skipped"Posts with at least one variant in this status
qquerystringSearch title and external_ref
external_refquerystringExact match

Responses

200A page of postsPostList

Errors: 401 403 429 — see Errors.

GET/api/v1/posts/{id}#

Get a post with its variants

scope posts:read

Poll this (or use webhooks) to follow each market's status. preview_url / video_url are relative paths under the same host, authenticated like the API.

Parameters

idrequiredpathstringPost id

Responses

200PostPost

▸200 response (213 lines)
json
{
  "id": "post_7f3k2Qx9Lm2Ab",
  "title": "Autumn midweek deal",
  "template_id": "tpl_sys_bold_hook",
  "brand_id": "brd_Kd8sL2pQw1",
  "source_language": "en",
  "fields": {
    "hook": "Wake up *inside* the forest",
    "body": "Midweek stays, three nights for the price of two.",
    "cta": "Book in bio"
  },
  "media": {
    "bg": "ast_Q2w8Lm4Kx0Pz"
  },
  "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
  "hashtags": [
    "autumn",
    "midweek"
  ],
  "brief": null,
  "status": "active",
  "external_ref": "cms-4711",
  "created_via": "api",
  "ai_generated": false,
  "brand_organic": false,
  "schedule_at": null,
  "created_at": 1795000000000,
  "updated_at": 1795000000000,
  "summary": {
    "markets": 3,
    "by_status": {
      "localizing": 2,
      "rendering": 1
    }
  },
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0
  },
  "variants": [
    {
      "id": "var_nl9Fk2LmQx81",
      "post_id": "post_7f3k2Qx9Lm2Ab",
      "market_id": "mkt_nl4Gh7Ns2Kd",
      "market": {
        "id": "mkt_nl4Gh7Ns2Kd",
        "name": "Netherlands",
        "country": "NL",
        "language": "nl",
        "flag": "🇳🇱"
      },
      "account_id": "acc_Wq81Lp0sZt3",
      "language": "nl",
      "status": "localizing",
      "status_label": "Localizing",
      "localized_by": null,
      "fields": {
        "hook": "…",
        "body": "…",
        "cta": "…"
      },
      "caption": "…",
      "hashtags": [
        "wildcamp",
        "glamping"
      ],
      "checks": [],
      "edited": false,
      "scheduled_at": null,
      "approval_id": null,
      "post_url": null,
      "tiktok_video_id": null,
      "published_at": null,
      "error": null,
      "render_error": null,
      "preview_url": null,
      "video_url": null,
      "metrics": {
        "views": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "avg_watch_time": null,
        "baseline_ratio": null,
        "is_winner": false,
        "synced_at": null
      },
      "links": {
        "self": "/api/v1/variants/var_nl9Fk2LmQx81",
        "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
        "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
      },
      "created_at": 1795000000000,
      "updated_at": 1795000000000
    },
    {
      "id": "var_de9Fk2LmQx81",
      "post_id": "post_7f3k2Qx9Lm2Ab",
      "market_id": "mkt_de4Gh7Ns2Kd",
      "market": {
        "id": "mkt_de4Gh7Ns2Kd",
        "name": "Germany",
        "country": "DE",
        "language": "de",
        "flag": "🇩🇪"
      },
      "account_id": "acc_Wq81Lp0sZt3",
      "language": "de",
      "status": "localizing",
      "status_label": "Localizing",
      "localized_by": null,
      "fields": {
        "hook": "…",
        "body": "…",
        "cta": "…"
      },
      "caption": "…",
      "hashtags": [
        "wildcamp",
        "glamping"
      ],
      "checks": [],
      "edited": false,
      "scheduled_at": null,
      "approval_id": null,
      "post_url": null,
      "tiktok_video_id": null,
      "published_at": null,
      "error": null,
      "render_error": null,
      "preview_url": null,
      "video_url": null,
      "metrics": {
        "views": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "avg_watch_time": null,
        "baseline_ratio": null,
        "is_winner": false,
        "synced_at": null
      },
      "links": {
        "self": "/api/v1/variants/var_de9Fk2LmQx81",
        "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
        "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
      },
      "created_at": 1795000000000,
      "updated_at": 1795000000000
    },
    {
      "id": "var_gb9Fk2LmQx81",
      "post_id": "post_7f3k2Qx9Lm2Ab",
      "market_id": "mkt_gb4Gh7Ns2Kd",
      "market": {
        "id": "mkt_gb4Gh7Ns2Kd",
        "name": "United Kingdom",
        "country": "GB",
        "language": "en",
        "flag": "🇬🇧"
      },
      "account_id": "acc_Wq81Lp0sZt3",
      "language": "en",
      "status": "rendering",
      "status_label": "Rendering",
      "localized_by": "source",
      "fields": {
        "hook": "Wake up *inside* the forest",
        "body": "Midweek stays, three nights for the price of two.",
        "cta": "Book in bio"
      },
      "caption": "Three nights in the forest, pay for two. Monday to Thursday.",
      "hashtags": [
        "wildcamp",
        "glamping"
      ],
      "checks": [],
      "edited": false,
      "scheduled_at": null,
      "approval_id": null,
      "post_url": null,
      "tiktok_video_id": null,
      "published_at": null,
      "error": null,
      "render_error": null,
      "preview_url": null,
      "video_url": null,
      "metrics": {
        "views": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "avg_watch_time": null,
        "baseline_ratio": null,
        "is_winner": false,
        "synced_at": null
      },
      "links": {
        "self": "/api/v1/variants/var_gb9Fk2LmQx81",
        "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
        "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
      },
      "created_at": 1795000000000,
      "updated_at": 1795000000000
    }
  ],
  "links": {
    "self": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  }
}

Errors: 401 403 404 429 — see Errors.

DEL/api/v1/posts/{id}#

Delete a post

scope posts:write

Published variants stay on TikTok; the post is then only hidden.

Parameters

idrequiredpathstringPost id

Responses

200Deleted

Errors: 401 403 404 429 — see Errors.

POST/api/v1/posts/{id}/markets#

Add markets to a post

scope posts:write

Parameters

idrequiredpathstringPost id

Request body · application/json

FieldTypeDescription
marketsstring[] | stringMarket ids, language or country codes, or ["all"]
locationsstring[] | stringLocation ids, slugs or external_ids to add
overridesmap<string, VariantOverride>
Example
{
  "markets": [
    "fr",
    "es"
  ],
  "overrides": {
    "fr": {
      "caption": "Trois nuits, payez-en deux."
    }
  }
}

Responses

200Post with all variantsPost

Errors: 401 403 404 400 429 — see Errors.

Variants#

One market's version of a post: edit, submit, approve, retry.

GET/api/v1/variants/{id}#

Get a variant

scope posts:read

Parameters

idrequiredpathstringVariant id

Responses

200VariantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 429 — see Errors.

PATCH/api/v1/variants/{id}#

Edit a variant's text

scope posts:write

Changing text re-renders the video. Not possible while pending approval/approved — withdraw first.

Parameters

idrequiredpathstringVariant id

Request body · application/json

FieldTypeDescription
fieldsmap<string, string>Slot key → text (merged). Changing text re-renders the video
captionstringmax length 2200
hashtagsstring[] | string
scheduled_atnumber | string | nullISO 8601 date-time (e.g. 2026-12-01T18:00:00+01:00), Unix milliseconds, or null
Example
{
  "fields": {
    "hook": "Wach *mitten* im Wald auf"
  },
  "caption": "Drei Nächte, zahl zwei."
}

Responses

200Updated variantVariant

Errors: 401 403 404 400 429 — see Errors.

POST/api/v1/variants/{id}/submit#

Submit for approval

scope posts:write

Locks the exact payload (account, video hash, final caption, disclosures, schedule) and adds it to the approval queue. Blocked while text checks have errors.

Parameters

idrequiredpathstringVariant id

Responses

200The updated variantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 429 — see Errors.

POST/api/v1/variants/{id}/withdraw#

Withdraw from approval

scope posts:write

Back to rendered so it can be edited.

Parameters

idrequiredpathstringVariant id

Responses

200The updated variantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 429 — see Errors.

POST/api/v1/variants/{id}/approve#

Approve and schedule

scope approvals:write

Approves the pending approval of this variant. Publishes at publish_at, the post's schedule, or now.

Parameters

idrequiredpathstringVariant id

Request body · application/json

FieldTypeDescription
publish_at"now" | number | string | null"now" (default: the post schedule or immediately), ISO date-time or Unix ms
Example
{
  "publish_at": "now"
}

Responses

200The updated variantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 400 429 — see Errors.

POST/api/v1/variants/{id}/reject#

Reject

scope approvals:write

A reason is required; it becomes a learning for the localizer.

Parameters

idrequiredpathstringVariant id

Request body · application/json

FieldTypeDescription
reasonrequiredstringWhy — the localizer learns from itmin length 1
Example
{
  "reason": "Hook is too formal for TikTok, use 'du'"
}

Responses

200The updated variantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 400 429 — see Errors.

POST/api/v1/variants/{id}/relocalize#

Re-run AI localization

scope posts:write

Discards edits and asks the AI again (optionally with a note).

Parameters

idrequiredpathstringVariant id

Request body · application/json

FieldTypeDescription
notestringInstruction for the new attempt, e.g. "less formal"max length 1000
Example
{
  "note": "Shorter hook, less formal"
}

Responses

200The updated variantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 400 429 — see Errors.

POST/api/v1/variants/{id}/retry#

Retry a failed variant

scope posts:write

Re-renders, or re-submits when the render exists.

Parameters

idrequiredpathstringVariant id

Responses

200The updated variantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 429 — see Errors.

POST/api/v1/variants/{id}/skip#

Skip this market

scope posts:write

This market won't get the post.

Parameters

idrequiredpathstringVariant id

Request body · application/json

FieldTypeDescription
reasonstring
Example
{
  "reason": "Offer not valid in this country"
}

Responses

200The updated variantVariant

200 response
{
  "id": "var_de9Fk2LmQx81",
  "post_id": "post_7f3k2Qx9Lm2Ab",
  "market_id": "mkt_de4Gh7Ns2Kd",
  "market": {
    "id": "mkt_de4Gh7Ns2Kd",
    "name": "Germany",
    "country": "DE",
    "language": "de",
    "flag": "🇩🇪"
  },
  "account_id": "acc_Wq81Lp0sZt3",
  "language": "de",
  "status": "pending_approval",
  "status_label": "Awaiting approval",
  "localized_by": "ai",
  "fields": {
    "hook": "Wach *mitten* im Wald auf",
    "body": "Drei Nächte zum Preis von zwei. Montag bis Donnerstag.",
    "cta": "Link in Bio"
  },
  "caption": "Drei Nächte im Wald, zahl nur zwei.",
  "hashtags": [
    "wildcamp",
    "glamping"
  ],
  "checks": [],
  "edited": false,
  "scheduled_at": null,
  "approval_id": "apr_Mx72Ld0QaP1",
  "post_url": null,
  "tiktok_video_id": null,
  "published_at": null,
  "error": null,
  "render_error": null,
  "preview_url": "/api/assets/ast_Th4mb9Lx2Q/file",
  "video_url": "/api/assets/ast_Rnd8Kq1Zp4/file",
  "metrics": {
    "views": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "avg_watch_time": null,
    "baseline_ratio": null,
    "is_winner": false,
    "synced_at": null
  },
  "links": {
    "self": "/api/v1/variants/var_de9Fk2LmQx81",
    "post": "/api/v1/posts/post_7f3k2Qx9Lm2Ab",
    "dashboard": "/app/posts/post_7f3k2Qx9Lm2Ab"
  },
  "created_at": 1795000000000,
  "updated_at": 1795000000000
}

Errors: 401 403 404 400 429 — see Errors.

Approvals#

The approval queue. Nothing is posted without a person (or approver key) approving it.

GET/api/v1/approvals#

Pending approvals

scope posts:read

Parameters

market_idquerystring
limitqueryintegerDefault 100

Responses

200Oldest first

Errors: 401 403 429 — see Errors.

Import#

Bulk-create posts from a spreadsheet.

POST/api/v1/import/csv#

Import posts from CSV

scope posts:write

One row per post; see the CSV guide for columns. Send multipart file or a text/csv body. ?dry_run=1 validates without creating anything.

Parameters

dry_runqueryboolean
template_idquerystringUsed for rows without a template_id
source_languagequerystring
marketsquerystringDefault markets for rows without a markets cell

Request body · text/csv

string

Example
title,template_id,markets,slot:hook,media:bg
Autumn,tpl_sys_bold_hook,all,Wake up in the forest,https://cdn.example.com/a.jpg

Request body · multipart/form-data

FieldTypeDescription
filerequiredstringCSV file (binary)binary

Responses

200Per-row resultsCsvImportResult

200 response
{
  "dry_run": false,
  "delimiter": ",",
  "columns": [
    "title",
    "template_id",
    "markets",
    "slot:hook",
    "media:bg"
  ],
  "unknown_columns": [],
  "summary": {
    "rows": 1,
    "ok": 1,
    "created": 1,
    "existing": 0,
    "failed": 0
  },
  "rows": [
    {
      "row": 1,
      "line": 2,
      "ok": true,
      "status": "created",
      "post_id": "post_7f3k2Qx9Lm2Ab",
      "variants": 5,
      "errors": []
    }
  ]
}

Errors: 401 403 400 429 — see Errors.

GET/api/v1/import/csv/template#

CSV header for a template

scope templates:read

Returns a CSV with the header row (base columns, slot:/media: columns, and <lang>:<slot> columns for your market languages) plus an example row.

Parameters

template_idrequiredquerystring
source_languagequerystring
delimiterquery"," | ";"
examplequerybooleanInclude an example row (default true)

Responses

200CSV file

200 response
title,template_id,source_language,markets,caption,hashtags,schedule_at,external_ref,ai_generated,brand_organic,slot:hook,media:bg,de:hook,de:caption

Errors: 401 403 429 — see Errors.

Analytics#

Results per market and top posts.

GET/api/v1/analytics/overview#

Overview

scope analytics:read

Parameters

daysqueryinteger1–365, default 28

Responses

200Pipeline, totals and per-market resultsAnalyticsOverview

Errors: 401 403 429 — see Errors.

GET/api/v1/analytics/top#

Top variants by views

scope analytics:read

Parameters

limitqueryinteger1–100, default 10
market_idquerystring

Responses

200Top variants

Errors: 401 403 429 — see Errors.

Webhooks#

Get notified when variants change status.

GET/api/v1/webhooks#

List webhooks

scope webhooks:write

Responses

200Webhooks (without secrets)

Errors: 401 403 429 — see Errors.

POST/api/v1/webhooks#

Create a webhook

scope webhooks:write

Events: variant.localized, variant.rendered, variant.pending_approval, variant.approved, variant.rejected, variant.published, variant.failed, boost.proposed, comment.received. The response contains the signing secret once.

Request body · application/json

FieldTypeDescription
urlrequiredstringuri
eventsrequired"*" | "variant.localized" | "variant.rendered" | "variant.pending_approval" | "variant.approved" | "variant.rejected" | "variant.published" | "variant.failed" | "boost.proposed" | "comment.received"[]Event types, or ["*"] for allmin 1 items
Example
{
  "url": "https://example.com/hooks/lokki",
  "events": [
    "variant.pending_approval",
    "variant.published",
    "variant.failed"
  ]
}

Responses

201Webhook incl. secretWebhook

201 response
{
  "id": "whk_Lp0Zx81Qm2",
  "url": "https://example.com/hooks/lokki",
  "events": [
    "variant.published"
  ],
  "active": true,
  "created_at": 1795000000000,
  "secret": "whsec_…"
}

Errors: 401 403 400 429 — see Errors.

DEL/api/v1/webhooks/{id}#

Delete a webhook

scope webhooks:write

Parameters

idrequiredpathstringWebhook id

Responses

200Deleted

Errors: 401 403 404 429 — see Errors.

Platform#

File downloads and health (outside /api/v1).

GET/api/v1/openapi.json#

This OpenAPI document

no auth

Responses

200OpenAPI 3.1 JSON

GET/api/assets/{id}/file#

Download asset bytes

Images, videos, renders and thumbnails of your workspace. Same auth as the API. Supports Range (206) for video scrubbing.

Parameters

idrequiredpathstringAsset id
downloadquerybooleanSend Content-Disposition: attachment

Responses

200File bytes

206Partial content

Errors: 401 404 429 — see Errors.

GET/api/fonts/{id}/file#

Download a font file

Built-in fonts are public; uploaded fonts need workspace auth.

Parameters

idrequiredpathstringFont id

Responses

200Font bytes

Errors: 401 404 429 — see Errors.

GET/api/health#

Health check

no auth

Responses

200Healthy

503Database unavailable