Zdroje Posty pro vývojáře: API, MCP, OpenAPI, CLI

K plánovači Posty se dostanete přes čtyři programovatelná rozhraní: veřejné REST API, MCP server, nástroj příkazového řádku a webhooky. Všechna spravují stejný účet, se stejnými oprávněními, která vidíte ve webovém rozhraní. Tahle stránka je referenční přehled. Nastavení jednotlivých klientů popisuje stránka AI agentů.

Na první pohled

Veřejné REST API

REST API odpovídá na adrese https://api.posty.hu. Veřejné cesty jsou pod předponou /public/v1. Spravuje stejný pracovní prostor jako webové rozhraní, jen přímo z vašeho kódu.

Autentizace

Každý požadavek nese API klíč v hlavičce Authorization. Klíč vytvoříte v Posty na stránce Automatizace → Pro vývojáře, nemusíte nám kvůli tomu psát. Klíč se ukáže jen jednou, hned po vytvoření. Později ho už nezobrazíme, uložte si ho hned. Klíče se dají omezit. Oprávnění se mění s aktuální rolí vlastníka. Klíč uživatele, který odejde z pracovního prostoru, přestane fungovat.

Pokud klíč patří k víc pracovním prostorům, hlavička showorg vybere, kterého se volání týká.

Co umí v1

• Výpis propojených sociálních účtů: GET https://api.posty.hu/public/v1/integrations
• Vytvoření a naplánování příspěvku: POST https://api.posty.hu/public/v1/posts
• Dotaz na kalendář, úprava, smazání: GET https://api.posty.hu/public/v1/posts, DELETE https://api.posty.hu/public/v1/posts/:id
• Nahrání médií ze souboru nebo z URL: POST https://api.posty.hu/public/v1/upload, POST https://api.posty.hu/public/v1/upload-from-url
• Odkaz k nahrání v prohlížeči, když je soubor na zařízení uživatele: POST https://api.posty.hu/public/v1/upload-link, GET https://api.posty.hu/public/v1/upload-link/:id
• Hledání dalšího volného termínu: GET https://api.posty.hu/public/v1/find-slot/:id
• Statistiky ke kanálu a příspěvku: GET https://api.posty.hu/public/v1/analytics/:integration

Stav a zjištění bez autentizace

GET https://api.posty.hu/public/v1/status je jediná cesta, která odpoví i bez klíče. Vrátí verzi API, přesný čas serveru v UTC a absolutní adresy všech dokumentů určených ke strojovému čtení: OpenAPI popis, OAuth metadata, MCP endpoint. Data pracovního prostoru nevrací a parametry nepřijímá. Agent z toho nejrychleji pozná, jestli nás dosáhne a kde hledat zbytek.

Chyby

Každá chyba vrací JSON. U chyb vyvolaných Posty nese lidskou větu pole msg. Volání, která neprojdou formální kontrolou požadavku, dostanou tvar frameworku (statusCode, message, error). 403 za oprávnění uvede chybějící scope a aktuální roli vlastníka klíče. Nejčastější příčina není špatně vytvořený klíč, ale uživatel se sníženou rolí. Schéma ApiError v OpenAPI dokumentu to popisuje strojově čitelně, u každého stavového kódu včetně toho, jestli má smysl opakovat.

Limity volání

Každá odpověď nese hlavičky RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (v sekundách) a RateLimit-Policy, s vlastním limitem na každou cestu. U 429 přijde i Retry-After. Nečekejte na 429. Podle zbývající hodnoty umíte zpomalit předem.

Verze a vyřazování

Verze je v cestě. Všechna veřejná volání žijí pod /public/v1. Nekompatibilní změna by přišla jako nová verze (/public/v2) a v1 by držela smlouvu. Rozšíření (nové volitelné pole, nová cesta, nová hodnota výčtu) probíhá uvnitř v1, takže váš klientský kód má ignorovat pole, která nezná.

Kdybychom cestu vyřadili, odpověď by dostala hlavičku Deprecation: true, v hlavičce Sunset datum, po kterém už nefunguje, a v hlavičce Link podrobnosti. Datum Sunset nikdy není blíž než 180 dní od první hlavičky Deprecation. Teď není nic ve vyřazování.

MCP server

Adresa MCP serveru je https://api.posty.hu/mcp, přenos streamable HTTP. Váš agent přes něj vidí stejné kanály a plánuje do stejného kalendáře jako vy.

• Klíč pro klienty: MCP klíč začínající psty_mcp_…, ze stránky Automatizace → Pro vývojáře. REST klíče začínající psty_… MCP server záměrně odmítá a taky řekne proč.
• Klíč pro aplikace: OAuth přístupový token začínající pos_…. Vyprší, jde obnovit a platí jen na adresu, pro kterou byl vystaven.
• Hotový blok nastavení pro Claude, ChatGPT, Muse, Hermes a OpenClaw zkopírujete na stránce Automatizace → Pro vývojáře. Popis je na stránce AI agentů.

Nástroj příkazového řádku

Balíček posty-cli je vydaný na npm. Instalace: npm install -g posty-cli, příkaz se jmenuje posty. Přihlášení se schválením v prohlížeči: posty auth:login.

V balíčku je SKILL.md, která popisuje všechny příkazy a přepínače. Agent, který má shell, se z ní naučí používání, aniž by četl web. CLI píše JSON odpověď na standardní výstup, stav a chyby na chybový výstup. Při neúspěšném běhu končí nenulovým kódem, takže volající program ví, co se stalo.

Předplatné přes agenta

Agent (Claude, CLI nebo REST klient) dovede člověka od věty „předplať mi Pro na rok“ až k běžícímu předplatnému. Jeden krok zůstává lidský: schválení platby na stránce Stripe Checkout, kde je obchodníkem Link. Agent ukáže plány, vyžádá odkaz a po zaplacení ověří, že plán běží.

• Funguje i bez účtu: z obrazovky souhlasu OAuth se člověk po přihlášení nebo registraci (e-mail nebo Google) vrátí ke stejné žádosti o souhlas. Nástroj MCP pro registraci neexistuje; přes REST a v CLI může agent účet také založit, viz níže.
• MCP: get_plans (čtyři plány, ceny a limity), subscribe (odkaz na Stripe Checkout pro zvolený plán), get_subscription (stav; tím agent po zaplacení potvrdí), manage_subscription (fakturační portál Stripe: změna plánu, zrušení, faktury, karta). Jen tyto nástroje smějí jmenovat plán a volají se jen tehdy, když se uživatel zeptá.
• REST: GET /plans, GET /subscription, POST /subscriptions/checkout, GET /subscription/portal. CLI: posty billing:plans, posty billing:subscribe --tier pro --period yearly, posty billing:status, posty billing:manage.
• Platba probíhá ve Stripe Checkout, vlastní peněženkou Link nebo kartou uživatele. Agent nikdy nesmí platit jednorázovou kartou ani kartou vydanou agentem: předplatné Posty se obnovuje měsíčně nebo ročně a jednorázová karta selže při prvním obnovení, čímž plán skončí.
• Pracovní prostor, jehož plán zatím nemá přístup k API, dostane přes MCP jen tyto čtyři nástroje; po zaplacení se ostatní objeví s dalším seznamem nástrojů. subscribe a manage_subscription fungují na připojeních vzniklých přihlášením (OAuth), pro plátce pracovního prostoru; přes REST je potřeba token OAuth nebo klíč psty_sa_ pro celý pracovní prostor. Na rozhraní ChatGPT není dostupný žádný ze čtyř nástrojů předplatného; tam se předplatné sjednává na posty.hu.

Založení účtu přes agenta

Agent (CLI, skript nebo asistent s nástrojem REST) může člověku založit účet Posty i bez prohlížeče. Účet je skutečný, aktivovaný a patří tomu člověku; agent k němu dostane klíč k celému pracovnímu prostoru.

• Kód e-mailem: POST /signup/start pošle na adresu člověka jednorázový kód. Člověk kód agentovi přečte a agent registraci dokončí voláním POST /signup/complete. Kód platí 10 minut.
• Člověk musí souhlasit s podmínkami: agent mu ukáže obchodní podmínky a zásady ochrany osobních údajů a pole acceptTerms: true pošle až po jeho souhlasu. Souhlas zaznamenáme stejně jako při registraci na webu.
• Takto založený účet nemá bezplatnou zkušební dobu. Dalším krokem je checkout: GET /plans, potom POST /subscriptions/checkout, a člověk zaplatí na stránce Stripe. API a MCP se otevřou jen s tarifem, který je obsahuje: apiAndMcpAccess: true v odpovědi GET /plans. Tarif Alap je neobsahuje, takže když si ho člověk vybere, agent mu předem řekne, že klíč ani po zaplacení k API přístup mít nebude. Kanály člověk připojí ve webové aplikaci.
• Pokud už adresa účet má, nový nevznikne: člověk se přihlásí příkazem posty auth:login nebo přes OAuth. Kdo se registruje v prohlížeči, zkušební dobu si ponechá.
• CLI: posty auth:signup --email [email protected], potom posty billing:plans a posty billing:subscribe --tier pro --period yearly.

Webhooky

Webhooky nastavíte v Posty a každé doručení je podepsané. Podpis přijde v hlavičce X-Posty-Signature, ve tvaru t=<unix sekund>,v1=<hex hmac-sha256>. Je to záměrně stejný tvar jako u Stripe, takže existující ověřovací knihovny s ním fungují.

• Podpis se počítá ze surového těla požadavku. Když ho váš framework nejdřív převede na JSON a znovu serializuje, dostanete jiný řetězec a ověření selže.
• Časové razítko je součástí podpisu. To je ochrana proti přehrání. Tolerance je 300 sekund.
• Tajný klíč k podpisu dostanete při vytvoření webhooku a v Posty ho můžete kdykoli znovu vygenerovat.

OAuth aplikace

Když nespravujete vlastní účet, ale účty jiných lidí z aplikace, použijete OAuth. Autorizace jde přes authorization code flow a následující je povinné.

• Výzva PKCE S256 u každého požadavku. Klient bez tajemství se zaregistrovat dá, bez PKCE ne.
• redirect_uri musí přesně odpovídat registrovanému seznamu.
• Tokeny vyprší a obnovovací token rotujeme. Ukládáme jen jejich hashovanou podobu.
• Token platí na scope, ke kterým uživatel dal souhlas. Při každém volání to protínáme s aktuální rolí uživatele. Snížení role se projeví na dalším volání.
• Aplikaci může povolit člen pracovního prostoru s rolí SUPERADMIN.

Přístup a první kroky

Celý postup je svépomocný. Nemusíte mluvit s obchodníkem ani žádat o demo.

• Zaregistrujete se na stránce /regisztracio. Registrace je zdarma.
• Propojíte sociální účty běžným OAuth postupem.
• Klíč vytvoříte na stránce Automatizace → Pro vývojáře: API klíč pro REST API a CLI, MCP klíč pro chat klienta.
• Každý tarif začíná 7denním zkušebním obdobím zdarma. Ke spuštění zkoušky chceme platební kartu, ale během zkoušky nic nestrhneme. Dnes neplatíte nic a před koncem to můžete kdykoli zrušit. Ceny ukazuje sekce cen.

Pro strojové čtení

Když píšete agenta, neparsujte HTML. Každá veřejná stránka webu má Markdown variantu: na konec cesty přidejte příponu .md, hlavní stránka je /index.md.

Když se zaseknete

Napište na [email protected], nebo použijte formulář na stránce Pomoc. V pracovních dnech obvykle odpovíme do jednoho dne.