☰ Menu

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.

1

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.

bash
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.

2

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.

bash
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"}}'
3

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.

bash
# 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.json

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.

4

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.

bash
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"}'
5

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.

bash
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"
}'
6

…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.

POST /posts body
{
  "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.
7

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.

bash
curl "$LOKKI/posts/post_…" -H "Authorization: Bearer $LOKKI_KEY" | jq '.variants[] | {language, status, video_url}'

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.

8

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.

bash
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"}'

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.

Next

Subscribe to variant.published and variant.failed with a webhook, or browse the API reference.