Posty API, MCP a CLI reference

Tato stránka je kompletní referenční příručka programovatelných rozhraní Posty: každý veřejný REST endpoint, všechny příkazy nástroje příkazové řádky a nástroje MCP serveru. Pokud jste se ještě nerozhodli, které rozhraní potřebujete, začněte přehledem pro vývojáře.

Ke každému endpointu je v kompletní dokumentaci samostatná stránka, s parametry a spustitelnými příklady: posty.hu/dokumentacio/api/vegpontok.

Jak to funguje

Posty přes tři rozhraní spravuje stejný pracovní prostor jako webová aplikace. REST API z vašeho vlastního kódu, nástroj příkazové řádky z terminálu a vašich skriptů, MCP server z AI agenta. Všechna tři používají stejná oprávnění a limity, proto co zvládnete na jednom, zvládnete i na ostatních.

Základní adresa REST API je https://api.posty.hu/public/v1. Verze je v cestě a každá odpověď je JSON.

Připojení ve třech krocích

1. Zaregistrujte se na posty.hu/regisztracio. Žádný prodejní hovor, žádná čekací listina.
2. V rozhraní propojte alespoň jeden sociální účet. Tento krok z API neuděláte, protože platforma chce souhlas od člověka.
3. Vytvořte si klíč: Automatizace → Vývojáři. Klíč se ukáže jen jednou, v okamžiku vytvoření.

Prvním voláním si ověříte, že je vše na svém místě. Tento endpoint odpoví i bez klíče a řekne vám, kde najdete všechno:

curl https://api.posty.hu/public/v1/status

První ověřené volání vypíše vaše kanály:

curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: psty_a_kulcsod"

Autentizace

Fungují dva typy přihlašovacích údajů. API klíč je celá hodnota hlavičky Authorization (psty_…) a je určený pro váš vlastní kód. Přístupový token OAuth 2.1 (Bearer pos_…) potřebujete, když k Posty přistupuje jiná aplikace jménem vašich uživatelů. Průběh používá PKCE a metadata jsou strojově čitelná.

Oprávnění klíče se řídí aktuální rolí jeho vlastníka. Když je někdo přeřazen na nižší roli nebo odebrán z pracovního prostoru, klíč umí hned jen to, co smí on. Pokud klíč patří k více pracovním prostorům, hlavička showorg mezi nimi vybere.

Endpointy

Každá cesta je pod https://api.posty.hu/public/v1. Sloupec „Oprávnění" ukazuje, jaký scope klíč potřebuje. Když chybí, odpověď je 403 a pojmenuje, co chybí.

Přesná schémata požadavku a odpovědi, pole po poli, najdete v popisu OpenAPI 3. Z něj si můžete nechat vygenerovat i kód klienta.

Příklad: naplánovaný příspěvek

Datum je vždy UTC, ve formátu ISO 8601. type může být draft, schedule nebo now.

curl -X POST https://api.posty.hu/public/v1/posts \
  -H "Authorization: psty_a_kulcsod" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2026-09-15T09:00:00.000Z",
    "shortLink": false,
    "posts": [{
      "integration": { "id": "id_vaseho_kanalu" },
      "value": [{ "content": "<p>Ahoj všichni!</p>" }]
    }]
  }'

Odpověď vrací jeden řádek na kanál, s hodnotou postId, kterou použijete při mazání a při změně stavu.

Chyby

Každá chyba je JSON. U chyb, které vyvolá Posty, nese lidskou větu pole msg. Volání, která neprojdou kontrolou formátu požadavku, dostanou tvar frameworku (statusCode, message, error). Oprávnění 403 pojmenuje chybějící scope a roli vlastníka klíče, protože nejčastější příčina není špatný klíč, ale uživatel se sníženou rolí.

Stavový kód řekne, jestli má smysl to zkusit znovu: 400, 401, 403 a 404 nezmizí, dokud něco nezměníte. 429 a 5xx ano. Schéma ApiError toto všechno popisuje i strojově čitelně v dokumentu OpenAPI.

Limity volání

Každá odpověď nese hlavičky RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (v sekundách, ne jako časové razítko) a RateLimit-Policy. S kódem 429 přijde i Retry-After. Každá cesta má vlastní okno, na klíč. Nečekejte na 429: ze zbývající hodnoty můžete zpomalit předem.

Verze a vyřazování

Verze je v cestě: každé veřejné volání žije pod /public/v1. Nekompatibilní změna by se objevila jako nová verze (/public/v2) a v1 si drží svou smlouvu. Rozšíření (nové volitelné pole, nová cesta, nová hodnota výčtu) probíhá uvnitř v1, proto váš kód ignoruje pole, která nezná.

Kdybychom cestu vyřazovali, odpověď by dostala hlavičku Deprecation: true a v hlavičce Sunset datum, po kterém už nebude fungovat. Toto datum není nikdy blíž než 180 dní. Každá odpověď nese i hlavičku Link se vztahem rel="sunset", která ukazuje na tuto sekci. Momentálně není nic ve vyřazování.

Nástroj příkazové řádky

posty-cli používá stejné API, jen z terminálu. Instalace a přihlášení:

npm install -g posty-cli
posty auth:login
posty integrations:list

Přihlášení otevře prohlížeč a klíč uloží na váš počítač, takže ho nemusíte vkládat do skriptů. Každý příkaz umí dát výstup --json, který je určený ke strojovému zpracování.

MCP server

Adresa MCP serveru je https://api.posty.hu/mcp-oauth, s přenosem streamable HTTP a autentizací OAuth 2.1. Váš agent vidí tyto nástroje:

Připojení žádá o autentizaci: bez přihlašovacích údajů server vrátí 401 a v hlavičce WWW-Authenticate řekne, kde požádat o oprávnění. To není chyba, ale začátek procesu podle standardu MCP. Seznam nástrojů se i tak dá přečíst z manifestu.

Strojově čitelné

Každý dokument, který agent nebo generátor požaduje:

• OpenAPI 3: https://posty.hu/openapi.json
• MCP manifest: https://posty.hu/.well-known/mcp.json
• Stav a zjištění: https://api.posty.hu/public/v1/status
• OAuth metadata: https://api.posty.hu/.well-known/oauth-protected-resource
• Krátké shrnutí pro agenty: https://posty.hu/llms.txt