Getting started
Quickstart
From zero to a localized post in every market: create a key, upload your font, push your template, import media, create a post (AI-localized or with your own translations), follow its status and approve it — all over the API.
Create an API key#
In the dashboard go to Settings → API keys → Create key. Pick the scopes you need — for this guide: posts:read, posts:write, assets:write, templates:read, templates:write, markets:read and (for step 8) approvals:write. Copy the secret; it is shown once.
export LOKKI_KEY="lk_live_…"
export LOKKI="https://uselokki.com/api/v1"
curl "$LOKKI/me" -H "Authorization: Bearer $LOKKI_KEY"You also need at least one market (Settings → Markets, or POST /markets) and, to publish, a TikTok account connected to it (Accounts → Connect). Everything up to approval works without an account.
Upload your font#
Upload one file per weight/style (.ttf, .otf, .woff, .woff2). Then point the brand kit's heading/body fonts at the family, so templates using brand.heading pick it up.
curl -X POST "$LOKKI/fonts" -H "Authorization: Bearer $LOKKI_KEY" \
-F file=@AcmeSans-Bold.otf -F family="Acme Sans" -F weight=700
curl -X PATCH "$LOKKI/brand" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" \
-d '{"fonts": {"heading": "Acme Sans"}, "colors": {"primary": "#FF5A1F"}}'import { readFile } from "node:fs/promises";
const API = "https://uselokki.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.LOKKI_KEY}`, "Content-Type": "application/json" };
const form = new FormData();
form.append("file", new Blob([await readFile("AcmeSans-Bold.otf")]), "AcmeSans-Bold.otf");
form.append("family", "Acme Sans");
form.append("weight", "700");
const font = await fetch(`${API}/fonts`, { method: "POST", headers: { Authorization: headers.Authorization }, body: form }).then((r) => r.json());
await fetch(`${API}/brand`, { method: "PATCH", headers, body: JSON.stringify({ fonts: { heading: "Acme Sans" } }) });import os, requests
API = "https://uselokki.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['LOKKI_KEY']}"}
with open("AcmeSans-Bold.otf", "rb") as f:
font = requests.post(f"{API}/fonts", headers=H, files={"file": f},
data={"family": "Acme Sans", "weight": "700"}).json()
requests.patch(f"{API}/brand", headers=H, json={"fonts": {"heading": "Acme Sans"}})Push your template#
A template is a JSON spec: slots (the inputs a post fills in), scenes with layers (text, images, shapes) and brand tokens. See Templates & fonts for the full reference. Keep the returned id.
# template.json = the full example from the Templates guide
curl -X POST "$LOKKI/templates" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" -d @template.jsonconst API = "https://uselokki.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.LOKKI_KEY}`, "Content-Type": "application/json" };
const template = await fetch(`${API}/templates`, {
method: "POST", headers,
body: JSON.stringify({
"name": "Bold hook",
"category": "custom",
"spec": spec /* see the Templates guide */
}),
}).then((r) => r.json());
console.log(template.id); // tpl_…import os, requests
API = "https://uselokki.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['LOKKI_KEY']}"}
template = requests.post(f"{API}/templates", headers=H, json={
"name": "Bold hook", "category": "custom",
"spec": spec, # see the Templates guide
}).json()
print(template["id"])Invalid specs return 400 with a list of problems. Not ready to design one? GET /templates lists system templates (tpl_sys_…) you can use directly or POST /templates/:id/duplicate.
Upload media from a URL#
Lokki downloads the file and stores it as an asset. You can also upload with multipart (-F file=@photo.jpg), or skip this step and put { "url": "…" } directly in the post's media.
curl -X POST "$LOKKI/assets" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://cdn.example.com/photos/forest-dome.jpg"}'const API = "https://uselokki.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.LOKKI_KEY}`, "Content-Type": "application/json" };
const asset = await fetch(`${API}/assets`, {
method: "POST", headers,
body: JSON.stringify({ url: "https://cdn.example.com/photos/forest-dome.jpg" }),
}).then((r) => r.json());
console.log(asset.id); // ast_…import os, requests
API = "https://uselokki.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['LOKKI_KEY']}"}
asset = requests.post(f"{API}/assets", headers=H,
json={"url": "https://cdn.example.com/photos/forest-dome.jpg"}).json()Create a post for all markets (AI localization)#
Give the source text per text slot in fields, the media per media slot, and markets: ["all"]. Each market gets a variant; non-source languages are localized by AI with your brand voice, glossary and market notes. external_ref makes the call idempotent.
curl -X POST "$LOKKI/posts" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" -d '{
"template_id": "tpl_…",
"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": "ast_…"
},
"caption": "Three nights in the forest, pay for two. Monday to Thursday.",
"hashtags": [
"autumn",
"midweek"
],
"markets": [
"all"
],
"external_ref": "cms-4711"
}'const API = "https://uselokki.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.LOKKI_KEY}`, "Content-Type": "application/json" };
const res = await fetch(`${API}/posts`, { method: "POST", headers, body: JSON.stringify({
"template_id": "tpl_…",
"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": "ast_…"
},
"caption": "Three nights in the forest, pay for two. Monday to Thursday.",
"hashtags": [
"autumn",
"midweek"
],
"markets": [
"all"
],
"external_ref": "cms-4711"
}) });
const { post, idempotent } = await res.json(); // 201 created, 200 = already existed
for (const v of post.variants) console.log(v.market.flag, v.language, v.status);import os, requests
API = "https://uselokki.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['LOKKI_KEY']}"}
r = requests.post(f"{API}/posts", headers=H, json={
"template_id": "tpl_…",
"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": "ast_…"
},
"caption": "Three nights in the forest, pay for two. Monday to Thursday.",
"hashtags": [
"autumn",
"midweek"
],
"markets": [
"all"
],
"external_ref": "cms-4711"
})
post = r.json()["post"]
for v in post["variants"]:
print(v["market"]["flag"], v["language"], v["status"])…or supply your own translations#
Send overrides keyed by market id, language or country code. Markets with an override skip the AI and use your text (localized_by: "manual"). translate: false guarantees no AI at all: markets without an override get the source text.
{
"template_id": "tpl_…",
"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_…"
},
"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"
}Many posts at once
POST /posts/bulk takes up to 100 of these bodies, and the CSV import takes a spreadsheet with de:hook, de:caption columns for your translations.Follow the status#
Each variant moves localizing → rendering → rendered → pending_approval → approved → publishing → published. Poll the post (every 5–10 s is fine) or, better, subscribe to webhooks. When rendered, preview_url (thumbnail) and video_url (mp4) are set — fetch them with the same Authorization header.
curl "$LOKKI/posts/post_…" -H "Authorization: Bearer $LOKKI_KEY" | jq '.variants[] | {language, status, video_url}'const API = "https://uselokki.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.LOKKI_KEY}`, "Content-Type": "application/json" };
const done = new Set(["pending_approval", "approved", "published", "failed", "rejected", "skipped"]);
let post;
do {
await new Promise((r) => setTimeout(r, 5000));
post = await fetch(`${API}/posts/${postId}`, { headers }).then((r) => r.json());
console.log(post.variants.map((v) => `${v.language}:${v.status}`).join(" "));
} while (!post.variants.every((v) => done.has(v.status)));import time
import os, requests
API = "https://uselokki.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['LOKKI_KEY']}"}
done = {"pending_approval", "approved", "published", "failed", "rejected", "skipped"}
while True:
post = requests.get(f"{API}/posts/{post_id}", headers=H).json()
print(" ".join(f"{v['language']}:{v['status']}" for v in post["variants"]))
if all(v["status"] in done for v in post["variants"]):
break
time.sleep(5)A variant with text problems stays rendered with checks listing them (e.g. a translation over maxChars). Fix it with PATCH /variants/:id and POST /variants/:id/submit.
Approve via the API#
Approvals normally happen in the dashboard (or the mobile swipe queue). If your own system does the review, list the queue and approve or reject — this needs a key with approvals:write. Approving publishes at the post's schedule_at, at publish_at, or now.
curl "$LOKKI/approvals" -H "Authorization: Bearer $LOKKI_KEY"
curl -X POST "$LOKKI/variants/var_…/approve" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" -d '{"publish_at": "2026-12-01T18:00:00+01:00"}'
curl -X POST "$LOKKI/variants/var_…/reject" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" -d '{"reason": "Hook too formal, use du"}'const API = "https://uselokki.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.LOKKI_KEY}`, "Content-Type": "application/json" };
const { data } = await fetch(`${API}/approvals`, { headers }).then((r) => r.json());
for (const a of data) {
console.log(a.market.flag, a.payload.caption); // exactly what will be posted
await fetch(`${API}/variants/${a.variant_id}/approve`, { method: "POST", headers, body: "{}" });
}import os, requests
API = "https://uselokki.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['LOKKI_KEY']}"}
for a in requests.get(f"{API}/approvals", headers=H).json()["data"]:
print(a["market"]["flag"], a["payload"]["caption"])
requests.post(f"{API}/variants/{a['variant_id']}/approve", headers=H, json={})The approval locks the exact payload: account, video hash, final caption, disclosure toggles and schedule. If anything changes afterwards (an edit, a re-render) the variant must be approved again. Rejections need a reason; Lokki learns from it for the next localization.