Občasník

Redakční nápověda · API-first

Podrobný postup pro autory

Občasník je nezávislá platforma pro články a analytické série. AI pomáhá s přípravou, lidé odpovídají za tvrzení i vydání. Odlišujte fakta doložená zdroji, vlastní odvození, hypotézy a neznámé skutečnosti.

Autorské API běží na veřejné adrese https://redakce.obcasnik.online. Návrhy a stav článku spravujte přes /api/v1/, nikoli přes administrátorské rozhraní. Zaregistrovat se v redakci →

← Stručný postup · Aktuální šablona · Aktuální skill

Cesta článku redakcí

draft → pending → approved → awaiting-deploy → published

  1. draft – soukromý rozpracovaný návrh autora.
  2. pending – odevzdáno k posouzení, stále neveřejné.
  3. approved – redakčně schváleno, ještě nevydáno.
  4. awaiting-deploy – vydání vyžádáno, čeká na nasazení a systémovou kontrolu.
  5. published – nasazení dokončeno, článek je veřejný.

1. Registrace a ověření

Pošlete veřejné zobrazované jméno nebo pseudonym (displayName) a neveřejný e-mail (email) jako JSON na POST /api/v1/auth/register. Odpověď obsahuje authorId a dočasný klíč. Před odevzdáním článku musíte adresu ověřit.

Výchozí postup: ověřovací odkaz GET /auth/verify?token=… otevře autor ve svém prohlížeči. GET zobrazí pouze potvrzovací formulář, bez spotřebování odkazu. Teprve potvrzení formulářem POST /auth/verify ověří e-mail a jednorázově zobrazí nový hlavní secret, který nahradí původní klíč. Alternativně lze jednorázový token vložit jako magicLinkToken na POST /api/v1/auth/login; odpověď rovněž obsahuje nový klíč. Přihlášení pomocí secret na stejném endpointu vrací identitu autora. Další volání používají hlavičku Authorization: Bearer …. Před ověřením adresy lze vytvořit nejvýše jeden návrh.

Při vypršení či ztrátě odkazu, včetně restartu služby (čekající odkazy nejsou trvale uloženy), požádejte o nový přes POST /api/v1/auth/resend-verification s JSON polem email, nebo odešlete formulář POST /auth/resend. Běžná úspěšná odpověď HTTP 200 ({"ok":true}) je záměrně stejná pro neznámý, ověřený i neověřený účet. HTTP 503 znamená dočasnou nedostupnost služby a může odrážet selhání odeslání či ověření; požadavek proto zopakujte později. Nový odkaz dostane pouze způsobilá adresa. Jednorázový token ani klíč nikomu nesdělujte.

Webové přihlášení přes POST /auth/session odešle odkaz na ověřený e-mail; autor jej sám potvrdí v prohlížeči. Autorský dashboard nabízí vlastní články, validaci, profil a správu tokenů. Cookie webové relace není přístupový token pro agentní API; autorské API používá Bearer.

Po ověření účtu si v autorském profilu můžete propojit veřejný autorský profil. Zobrazí se návrh veřejného ID odvozený ze zobrazovaného jména displayName; před vytvořením ho můžete upravit (nejvýše 64 znaků), po propojení už ne. Vyplňte veřejné jméno, medailonek a volitelnou roli a výslovně odsouhlaste zveřejnění. Nově vytvořený profil je po uložení veřejný bez předchozího redakčního schválení profilu. Později lze tyto tři údaje upravit samoobslužně, také bez předchozího redakčního schválení úprav profilu. Existující historický profil se nabízí k převzetí jen po individuálním výslovném povolení redakcí; výchozí seznam povolených profilů je prázdný. Pro propojení stačí ověřená webová relace, další přístup do e-mailové schránky není potřeba. Hlavní Bearer token smí vytvořit, převzít nebo upravit veřejný profil stejného autora na GET/POST /api/v1/author/my/public-profile (identity určuje sám token, bez cílového autora); agentní token tam nemá přístup a vrací 403 insufficient-scope. V článku pole authors nadále obsahuje veřejné slugy autorů, ne interní ID účtů; schvalování a zveřejnění článku zůstává oddělené a výhradně na redakci.

Nový pojmenovaný agentní token vyžaduje explicitní seznam scopes. profile:read vrací pouze omezený profil bez e-mailu a tokenů, drafts:read dovoluje GET /api/v1/drafts, detail a validaci, drafts:write zápis a smazání, drafts:submit odevzdání a publish:request žádost o vydání. Historie po smazání draftu zůstává neveřejnou auditní stopou.

2. Napište a vložte návrh

Stáhněte šablonu Markdown (neměnná verze v2). Vyplňte YAML metadata title, description, series, topics, authors a obsah; zachovejte explicitní status: draft. Soubor musí začínat prvním řádkem --- a frontmatter ukončit dalším samostatným ---. Chybějící či neplatná povinná pole okamžitě odmítnou odevzdání i schválení (uložení konceptu jen upozorní). Rozlišujte fakta se zdroji, odvození, hypotézy a známé/neznámé skutečnosti podle šablony.

Celý Markdown včetně frontmatteru odešlete jako JSON {"content":"…"} na POST /api/v1/drafts. Můžete ho načíst ze souboru a bezpečně zakódovat do JSON (např. jq --rawfile content clanek.md), nebo přímo vložit text do pole content. Nevytvářejte JSON ručním spojováním řetězců. Odpověď 201 obsahuje article_id, revision a state: draft.

Přes GET /api/v1/drafts/{article_id} zjistíte aktuální stav a revizi. Pro změnu obsahu použijte PATCH /api/v1/drafts/{article_id} s JSON poli content a aktuální číselnou revision; zastaralá revize vrací 409.

3. Odevzdání a schválení

GET /api/v1/rules přijímá platný hlavní i agentní autorský Bearer token bez dalšího scope a vrací aktuální pravidla. Chybějící či neplatný Bearer vrací 401, nedostupná služba 503. Při nedostupnosti katalogu vrací aplikace stabilní JSON kód (např. rules-unavailable); zastaralá data se nikdy nevracejí — po obnově služby si nechte pravidla znovu načíst.

Po kontrole textu a výslovném souhlasu autora odešlete POST /api/v1/drafts/{article_id}/submit s objektem declarations: rights_confirmed, sources_and_ai_disclosed a license_accepted musí pravdivě potvrdit autor, rules_version odpovídá aktuálním pravidlům (nyní v1). Stav draft → pending znamená odevzdáno, nikoli zveřejněno. Stav sledujte přes GET a čekejte na approved.

Po rejected opravte skutečný obsah a odešlete PATCH s aktuální revizí. V současné implementaci tato změna návrh automaticky znovu odevzdá jako pending se zachovanými prohlášeními; /submit podruhé neposílejte. Změna schváleného textu rovněž vrací článek do pending a vyžaduje nové schválení.

Výjimka: důvěryhodný autor může po odevzdání a úspěšné technické kontrole přejít rovnou do awaiting-deploy. Status trusted přiděluje pouze administrátor ručně; nejde o samozvolenou možnost ani automatický nárok.

Existují dva různé kroky: publish:request nastaví awaiting-deploy; pouze agent s výslovně uděleným publish:execute smí volat POST /api/v1/drafts/{article_id}/publish-execute. Tento krok spouští standardní validovanou, auditovanou publikaci s potvrzením nasazení; hlavní token ani starší agent bez explicitního scope jej nedostanou.

4. Žádost o vydání

Jen pro approved po samostatném výslovném souhlasu autora k datu a článku pošlete POST /api/v1/drafts/{article_id}/publish s JSON polem publish_date: platné ISO kalendářní datum YYYY-MM-DD, dnes nebo v budoucnu podle UTC. Úspěšná odpověď nastaví awaiting-deploy a plánovaný čas na půlnoc UTC. Na published přejde článek teprve po systémové kontrole nasazení. Po stažení vydaného článku přechází stav published → withdrawn a veřejně zůstává tombstone, nikoli obsah článku.