API: posts to the planner and photos for your website

The API is for the developer of your website or CMS, or for tools like Make, Zapier or n8n. Through it you send a finished post to the planner — text, photos or videos, which networks, when, and whether it goes out automatically or a person publishes it by hand. With the same key your website can also fetch photos and videos from the library.

Key

1. In the application open Settings → API and integrations.
2. Click Issue key and choose what it may do: only prepare posts, prepare and publish posts, or read the library.
3. Copy the key right away — it is shown only once. Only its fingerprint stays in the database.

The key is sent in the header Authorization: Bearer <key>, the API address is https://theis.cz/api/v1.

Send a post to the planner

curl -X POST https://theis.cz/api/v1/prispevky \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The final is over!",
    "site": ["instagram", "facebook"],
    "media": ["https://your-site.com/photo.jpg"],
    "kdy": "2026-10-20T18:00",
    "stav": "naplanovat",
    "nastaveni": { "instagram": { "rezim": "rucne", "kdo": "jana@company.com" } }
  }'

The response returns the post id , its status, the status on each network and a link into the app. The post shows up in the planner right away.

What you can send

• text — the shared text of the post.
• site — where it goes: youtube, instagram, facebook, tiktok, threads, linkedin.
• texty — a custom text for one network, e.g. a shorter version for Threads.
• media — addresses of photos, videos or PDFs. THEIS downloads them. Upload large files via /soubory (below).
• nahledovka — the video cover (a photo address). If you don't send one, THEIS takes a frame from the video itself so the planner has something to show.
• kdy — publishing time. Without a time zone, Czech time is assumed.
• stav — koncept (default), kontrola, or naplanovat.
• kontroluje a poznamka — for the status kontrola the e-mail of the colleague who reviews the post, and a note for them.
• rezim — auto (default), or rucne. Can also be set for each network separately.
• kdo — in manual mode, the e-mail of the person who gets a notification that it is their turn. Without it, the key’s author gets it.
• nastaveni — for each network separately: typ (prispevek, reel, story; for YouTube video or short), ucet, rezim, kdo, prvni_komentar, for YouTube nazev a viditelnost, for Threads vlakno a anketa.
• nastaveni.instagram.hudba — music from the Instagram library for a Reel (see below).
• nastaveni.tiktok — visibility, interactions, ad disclosure and consent for TikTok (see below).
• odkaz — a link post with a page preview (Facebook, LinkedIn, Threads).
• stitky — labels in the planner.
• externi_id — your own reference for the post. Sending the same one again creates nothing new, so a retry never publishes a post twice.

Draft, review, or straight to publishing

• koncept — the post waits in the planner until someone approves it. It is saved even when incomplete, and the response lists what is missing.
• kontrola — the post goes to a specific person for review, who gets a notification. They need the permission to approve.
• naplanovat — the post is queued for publishing at the time in kdy. Only with a key that may publish posts. If something breaks a network’s rules, the API rejects it and says why.

Automatic or manual

In auto mode the post goes out by itself at the given time. In rucne mode, at the given time the person in kdo gets a notification and publishes the post themselves — handy for Stories with stickers, or for a network where you want the last word.

Music for an Instagram Reel

To a Reel — a single video posted as a Reel or a Post — the API can add a track from the Instagram music library. You choose it in nastaveni.instagram.hudba:

• "trend" — the track that is trending most at the moment of publishing. {"trend": 3} takes the third one.
• {"id": "…"} — a specific track. The id is returned by GET /hudba.
• {"hledat": "…", "poradi": 1} — a track from a search by title or artist; without poradi the first one.

Volume is set in hlasitost_hudby a hlasitost_videa (1 to 100) — for example when the spoken word in the video should come through.

"nastaveni": { "instagram": { "typ": "reel", "hudba": { "trend": 1, "hlasitost_videa": 30 } } }

GET /hudba lists what is trending on Instagram right now, and with ?hledat=… it searches. The choice is smaller than in the Instagram app — it only holds tracks Instagram allows to be used outside its own app. Instagram cannot add music through the API to a photo, a carousel or a Story.

TikTok

TikTok publishes a post automatically only when you send in nastaveni.tiktok the same things a person fills in in the app. Nothing is pre-filled:

• viditelnost — required: vsichni, pratele, sledujici, or jen_ja. The account must offer that option; THEIS checks which ones it has with TikTok right when the post arrives.
• souhlas — must be true: consent to TikTok's Music Usage Confirmation, and for paid partnerships also to the Branded Content Policy.
• komentare, duet, stitch — true, or false (default). Whatever the account has switched off in its TikTok settings stays off.
• oznaceni — zadne (default), vlastni (you promote yourself), placena (paid partnership), or obe. A paid partnership must not have the visibility jen_ja.

"nastaveni": { "tiktok": { "viditelnost": "vsichni", "souhlas": true, "komentare": true } }

Without visibility and consent, TikTok goes as a draft, for review, or in manual mode.

Large photos and videos

Via an address in media THEIS takes photos up to 25 MB, videos up to 500 MB and PDFs up to 110 MB. Upload a larger file directly:

1. POST /soubory s {"soubor": "video.mp4"} returns the address nahrat.
2. Send the file to that address with the method PUT with the header Content-Type.
3. Then reference it in the post as {"soubor": "…"} with the value returned by the first step.

How the post is doing

GET /prispevky/<id> returns the post status (koncept, kontrola, naplanovano, vydano, chyba) and, for each network separately, whether it is waiting in the queue, waiting for a person, already published — with a link to the published post — or what went wrong. GET /prispevky lists the posts created by this key.

Editing and deleting

PATCH /prispevky/<id> changes what you send — the rest stays. DELETE /prispevky/<id> deletes the post. Both work only until the post goes out and as long as nobody has edited it in the app in the meantime, so the API never overwrites a person’s work.

Network rules

The same rules apply as in the app. Instagram takes only JPG photos up to 8 MB, YouTube only one video with a title, a Reel can only be made from a video, and Threads takes text up to 500 characters.

TikTok publishes automatically only with visibility and consent filled in (see above).

GET /site lists the connected accounts and the networks the key may publish to.

Photos and videos from the library for your website

A library key returns approved photos and videos: GET /media with a list (filters by event, label and changes since a date) and GET /media/<id> with a single item. Each comes with a thumbnail, a larger version and the original — nothing is converted.