☰ Menu

Guides

CSV import

Plan a month of content in a spreadsheet: one row per post. Upload it in the dashboard or via the API. Rows are validated one by one, so a typo in row 17 doesn't stop the other 99.

Columns#

Header names are case-insensitive and can be in any order. Only title and template_id are required (the template can also come from ?template_id=).

ColumnValue
titleInternal title (required)
template_idTemplate id, e.g. tpl_sys_bold_hook or one of yours
source_languageLanguage of the source text, e.g. en (default en)
marketsComma or semicolon list of market ids, language or country codes, or all (default all)
captionSource caption
hashtagsSeparated by spaces, commas or semicolons; # optional
schedule_atISO 8601 (2026-12-01T18:00:00+01:00), 2026-12-01 18:00, or Unix seconds/ms. Empty = as soon as approved
external_refYour id; re-importing the same row returns the existing post (status existing)
ai_generatedtrue/false — TikTok AI-generated content label
brand_organictrue/false — "Promotional content" disclosure
briefOptional guidance for the localizer
translatefalse = never use AI for this row
slot:<key>Source text for the template's text slot <key>
media:<key>URL (https://…, downloaded) or asset id (ast_…) for media slot <key>
<lang>:<key>Your own translation of slot <key> for that market — <lang> may be a language (de), country (AT) or market id
<lang>:captionYour own caption for that market
<lang>:hashtagsYour own hashtags for that market
  • A market with any <lang>: cell filled uses your text and is not sent to the AI; its empty cells fall back to the source text, so fill every text slot (and the caption) for that language. Markets without <lang>: cells are localized by AI.
  • Delimiter , or ; is detected from the header (Excel in many European locales saves with ;). Tabs work too.
  • RFC 4180 quoting: wrap cells containing the delimiter, quotes or line breaks in "…", and double quotes inside (""). A UTF-8 BOM is fine.
  • Up to 500 rows and 5 MB per file. Blank lines are ignored.

Example#

posts.csv
title,template_id,source_language,markets,caption,hashtags,schedule_at,external_ref,slot:hook,slot:body,media:bg,de:hook,de:caption,nl:hook
Autumn midweek deal,tpl_sys_bold_hook,en,all,"Three nights, pay for two.",autumn midweek,2026-12-01T18:00:00+01:00,cms-4711,Wake up *inside* the forest,"Mon–Thu, three nights for the price of two.",https://cdn.example.com/forest.jpg,Wach *mitten* im Wald auf,"Drei Nächte, zahl zwei.",
Winter cabins,tpl_sys_bold_hook,en,de; nl,"Cosy cabins, open all winter.",winter,,cms-4712,Your winter hideout,"Wood stove, starry sky, zero noise.",ast_Q2w8Lm4Kx0Pz,,,Jouw winterschuilplaats

Get the header for a template#

Download a ready-made header (plus an example row) for a template: base columns, a slot:/media: column per slot, and <lang>: columns for your markets' languages.

bash
curl "https://uselokki.com/api/v1/import/csv/template?template_id=tpl_sys_bold_hook&delimiter=;" \
  -H "Authorization: Bearer $LOKKI_KEY" -o posts.csv

Import#

Validate first with ?dry_run=1 (nothing is created, URLs are not downloaded), then import for real.

bash
# dry run
curl -X POST "https://uselokki.com/api/v1/import/csv?dry_run=1" -H "Authorization: Bearer $LOKKI_KEY" \
  -F file=@posts.csv

# import (text/csv body works too)
curl -X POST "https://uselokki.com/api/v1/import/csv" -H "Authorization: Bearer $LOKKI_KEY" \
  -H "Content-Type: text/csv" --data-binary @posts.csv

Result#

Always HTTP 200 with one entry per data row. row counts data rows from 1; line is the line in the file (the header is line 1), handy for spreadsheet users.

json
{
  "dry_run": false,
  "delimiter": ",",
  "columns": [
    "title",
    "template_id",
    "source_language",
    "markets",
    "caption",
    "hashtags",
    "schedule_at",
    "external_ref",
    "slot:hook",
    "slot:body",
    "media:bg",
    "de:hook",
    "de:caption",
    "nl:hook"
  ],
  "unknown_columns": [],
  "summary": {
    "rows": 2,
    "ok": 1,
    "created": 1,
    "existing": 0,
    "failed": 1
  },
  "rows": [
    {
      "row": 1,
      "line": 2,
      "ok": true,
      "status": "created",
      "post_id": "post_7f3k2Qx9Lm2Ab",
      "variants": 5,
      "errors": []
    },
    {
      "row": 2,
      "line": 3,
      "ok": false,
      "status": "error",
      "errors": [
        "No markets match de; nl"
      ]
    }
  ]
}
statusMeaning
createdA new post was created (post_id, variants = number of markets)
existingA post with this external_ref already existed; nothing changed
validDry run: the row would be created
errorSee errors — the row was skipped
Unknown columns are listed in unknown_columns and ignored — check it for typos like slot:hok.