☰ Menu

Lokki API · v1

One post in. A local video out, per market.

Lokki runs many TikTok Business accounts — one per country or language — from one place. Push a post from your CMS, PIM or scripts; Lokki localizes it, renders it into your own templates and fonts, routes each version to the right account and publishes it after approval.

How the pipeline works#

Every post fans out into one variant per market. Each variant moves through the pipeline on its own, so a slow approval in Germany never holds up the Netherlands.

  1. 01

    Post

    You push one idea: template, source text per slot, media.

  2. 02

    Variants

    Lokki creates one variant per market (country / language / account).

  3. 03

    Localize

    AI translation with your brand voice — or your own translations.

  4. 04

    Render

    Text goes into your template with your fonts → 9:16 mp4.

  5. 05

    Approve

    A person (or an approver key) approves the exact payload.

  6. 06

    Publish

    Posted to that market's TikTok account via the official API.

  7. 07

    Webhooks

    Every status change is pushed to your endpoint, signed.

Example: one post, three markets

POST /api/v1/posts

“Wake up inside the forest”

source: en · template: Bold hook

🇳🇱Word wakker midden in het bospending_approval
🇩🇪Wach mitten im Wald aufapproved
🇬🇧Wake up inside the forestpublished
  • Localize — markets in the source language get the source text. Others are localized by AI using your brand tone, glossary and the market's notes and approved offers — unless you send overrides with your own text, or translate: false.
  • Render — the template spec is drawn with your fonts and brand colours into a 1080×1920 mp4 + thumbnail. Text that is too long auto-shrinks; hard limits (maxChars) and forbidden words become text checks that block approval.
  • Approve — the approval stores exactly what will be posted (account, video hash, final caption, disclosure toggles, schedule). Any change means a new approval. Nothing is posted without one.
  • Publish — at the scheduled time, the worker publishes through TikTok's API (daily caps respected) and polls until the video is live; then metrics sync periodically.

Variant statuses

StatusLabelMeaning
localizingLocalizingAI is translating/adapting the text for this market.
renderingRenderingThe video is being rendered with your template and fonts.
renderedReady for reviewReady for review. Submit it (or it is auto-submitted when the market allows).
pending_approvalAwaiting approvalIn the approval queue. The payload is locked.
approvedApprovedApproved; waiting for its publish time.
publishingPublishingUploading to TikTok / waiting for TikTok to process.
publishedLiveLive. post_url is set and metrics sync periodically.
rejectedRejectedRejected with a reason. Edit and resubmit.
failedFailedLocalization, rendering or publishing failed. See error; retry.
skippedSkippedThis market won't get the post.

Authentication#

Create an API key in the dashboard under Settings → API keys (admins only) and pick its scopes. Send it as a bearer token. Keys belong to one workspace; the secret is shown once.

bash
curl https://app.example.com/api/v1/me \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxx"
ScopeAllows
posts:readRead posts, variants, assets and the approval queue
posts:writeCreate, edit, submit, retry and delete posts; CSV import
assets:writeUpload media and fonts, import media from URLs
templates:readRead templates, fonts and the brand kit
templates:writeCreate/update templates, the brand kit and markets
markets:readRead markets and connected TikTok accounts
approvals:writeApprove or reject variants (publishing!)
analytics:readRead results
webhooks:writeManage webhooks

Approvals are powerful

A key with approvals:write can approve posts for publishing. Give it only to systems that implement your own review step.

Requests from the dashboard use the session cookie instead; the same endpoints work, checked against the person's role.

Errors#

Errors always have the same shape. Validation errors list the offending field paths in details.

json
{
  "error": {
    "message": "Invalid request body",
    "details": [
      {
        "path": "fields.hook",
        "message": "Invalid input: expected string, received number",
        "code": "invalid_type"
      }
    ]
  }
}
StatusWhen
400Invalid body or query, unknown slot keys, unknown markets, text checks failing on submit
401Missing or invalid API key
403Key lacks a scope, or the user's role is too low
404Not found in your workspace (other workspaces' ids are always 404)
409State conflict, e.g. approving a variant that is not pending approval
413Upload too large
429Rate limited — see Retry-After

Rate limits#

Each API key can make 120 requests per minute (fixed window). Every response carries the current state:

http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1795000060

When you exceed it you get 429 with Retry-After (seconds). Use POST /posts/bulk (up to 100 posts per call) or the CSV import for large batches.

Idempotency#

Send your own id as external_ref (a CMS entry id, a SKU). If a post with that external_ref already exists, POST /posts returns it with HTTP 200 and "idempotent": true instead of creating a duplicate — safe to retry after a timeout. New posts return 201.

Conventions#

  • Base URL: https://<your Lokki host>/api/v1. JSON in and out (Content-Type: application/json), multipart for uploads.
  • Timestamps in responses are Unix milliseconds. Inputs accept ISO 8601 (2026-12-01T18:00:00+01:00) or Unix ms.
  • Lists: GET /posts returns { data, has_more, next_cursor }; pass cursor for the next page.
  • preview_url and video_url are paths on the same host; fetch them with the same Authorization header. Videos support Range.
  • Markets can be addressed by id (mkt_…), language (de), country (DE) or all.