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.
Quickstart →
API key → template → first post in 10 minutes.
API reference →
Every endpoint with examples. OpenAPI 3.1.
Templates & fonts →
Bring your own design system.
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.
- 01
Post
You push one idea: template, source text per slot, media.
- 02
Variants
Lokki creates one variant per market (country / language / account).
- 03
Localize
AI translation with your brand voice — or your own translations.
- 04
Render
Text goes into your template with your fonts → 9:16 mp4.
- 05
Approve
A person (or an approver key) approves the exact payload.
- 06
Publish
Posted to that market's TikTok account via the official API.
- 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
- 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
overrideswith your own text, ortranslate: 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
| Status | Label | Meaning |
|---|---|---|
localizing | Localizing | AI is translating/adapting the text for this market. |
rendering | Rendering | The video is being rendered with your template and fonts. |
rendered | Ready for review | Ready for review. Submit it (or it is auto-submitted when the market allows). |
pending_approval | Awaiting approval | In the approval queue. The payload is locked. |
approved | Approved | Approved; waiting for its publish time. |
publishing | Publishing | Uploading to TikTok / waiting for TikTok to process. |
published | Live | Live. post_url is set and metrics sync periodically. |
rejected | Rejected | Rejected with a reason. Edit and resubmit. |
failed | Failed | Localization, rendering or publishing failed. See error; retry. |
skipped | Skipped | This 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.
curl https://app.example.com/api/v1/me \
-H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxx"| Scope | Allows |
|---|---|
posts:read | Read posts, variants, assets and the approval queue |
posts:write | Create, edit, submit, retry and delete posts; CSV import |
assets:write | Upload media and fonts, import media from URLs |
templates:read | Read templates, fonts and the brand kit |
templates:write | Create/update templates, the brand kit and markets |
markets:read | Read markets and connected TikTok accounts |
approvals:write | Approve or reject variants (publishing!) |
analytics:read | Read results |
webhooks:write | Manage webhooks |
Approvals are powerful
A key withapprovals: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.
{
"error": {
"message": "Invalid request body",
"details": [
{
"path": "fields.hook",
"message": "Invalid input: expected string, received number",
"code": "invalid_type"
}
]
}
}| Status | When |
|---|---|
400 | Invalid body or query, unknown slot keys, unknown markets, text checks failing on submit |
401 | Missing or invalid API key |
403 | Key lacks a scope, or the user's role is too low |
404 | Not found in your workspace (other workspaces' ids are always 404) |
409 | State conflict, e.g. approving a variant that is not pending approval |
413 | Upload too large |
429 | Rate limited — see Retry-After |
Rate limits#
Each API key can make 120 requests per minute (fixed window). Every response carries the current state:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1795000060When 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 /postsreturns{ data, has_more, next_cursor }; passcursorfor the next page. preview_urlandvideo_urlare paths on the same host; fetch them with the sameAuthorizationheader. Videos supportRange.- Markets can be addressed by id (
mkt_…), language (de), country (DE) orall.