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=).
| Column | Value |
|---|---|
title | Internal title (required) |
template_id | Template id, e.g. tpl_sys_bold_hook or one of yours |
source_language | Language of the source text, e.g. en (default en) |
markets | Comma or semicolon list of market ids, language or country codes, or all (default all) |
caption | Source caption |
hashtags | Separated by spaces, commas or semicolons; # optional |
schedule_at | ISO 8601 (2026-12-01T18:00:00+01:00), 2026-12-01 18:00, or Unix seconds/ms. Empty = as soon as approved |
external_ref | Your id; re-importing the same row returns the existing post (status existing) |
ai_generated | true/false — TikTok AI-generated content label |
brand_organic | true/false — "Promotional content" disclosure |
brief | Optional guidance for the localizer |
translate | false = 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>:caption | Your own caption for that market |
<lang>:hashtags | Your 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 winterschuilplaatsGet 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.csvImport#
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.csvjs
import { readFile } from "node:fs/promises";
const res = await fetch("https://uselokki.com/api/v1/import/csv?dry_run=1", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.LOKKI_KEY}`, "Content-Type": "text/csv" },
body: await readFile("posts.csv"),
});
const report = await res.json();
for (const r of report.rows.filter((r) => !r.ok)) console.log(`line ${r.line}:`, r.errors.join("; "));python
import os, requests
with open("posts.csv", "rb") as f:
report = requests.post("https://uselokki.com/api/v1/import/csv", params={"dry_run": 1},
headers={"Authorization": f"Bearer {os.environ['LOKKI_KEY']}"},
files={"file": f}).json()
for r in report["rows"]:
if not r["ok"]:
print("line", r["line"], "; ".join(r["errors"]))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"
]
}
]
}| status | Meaning |
|---|---|
created | A new post was created (post_id, variants = number of markets) |
existing | A post with this external_ref already existed; nothing changed |
valid | Dry run: the row would be created |
error | See errors — the row was skipped |
Unknown columns are listed in
unknown_columns and ignored — check it for typos like slot:hok.