Deweloperzy

Artykuły jako element Twojego systemu

REST API z opisem OpenAPI, webhooki z podpisem HMAC i serwer MCP. Wszystko, co robisz w panelu, zrobisz też z kodu.

Szybki start

Od tokenu do opublikowanego tekstu w trzech krokach

  1. 1

    Utwórz token

    W Ustawienia → Tokeny API wybierz zakresy i projekty. Token zaczyna się od psk_live_ i widzisz go tylko raz.

  2. 2

    Zamów artykuł

    Wyślij brief z nagłówkiem Idempotency-Key. Odpowiedź 202 zawiera ticket i linki do statusu, treści i zdarzeń.

  3. 3

    Odbierz webhook

    Po zakończeniu Pennao wysyła article.completed z wynikiem jakości, kosztem i linkiem do treści.

zlecenie.sh

curl -X POST "$PENNAO_URL/v1/articles" \
  -H "Authorization: Bearer $PENNAO_TOKEN" \
  -H "Idempotency-Key: battery-2026-11-17" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_01K7…",
    "brief": {
      "title": "Czy fotowoltaika z magazynem się opłaca?",
      "keywords": { "primary": "opłacalność fotowoltaiki" },
      "intent": "commercial"
    },
    "settings": { "languages": ["pl", "en", "de"], "includeFaq": true }
  }'

# 202 Accepted
{ "ticket": "art_01K7…", "status": "queued" }
REST API

Najczęściej używane endpointy

Błędy w formacie application/problem+json, paginacja kursorem i limity zwracane jako 429 z Retry-After. Pełna lista w interaktywnej dokumentacji.

POST /v1/articles nowe zlecenie, odpowiedź 202 z ticketem
GET /v1/articles/{ticket} status, etap, postęp, koszt i wynik jakości
GET /v1/articles/{ticket}/events postęp na żywo (Server-Sent Events)
GET /v1/articles/{ticket}/content Markdown, HTML albo JSON w wybranym języku
POST /v1/articles/{ticket}/approve-plan zatwierdzenie planu przed pisaniem
POST /v1/articles/{ticket}/translations nowe wersje językowe gotowego tekstu
POST /v1/validate kontrola jakości dowolnego tekstu
POST /v1/webhooks nowy webhook z sekretem do podpisów
Webhooki

Zdarzenia, na które może reagować Twój system

Każde dostarczenie ma nagłówek Pennao-Signature z podpisem HMAC-SHA256 i znacznikiem czasu. Odpowiedź inna niż 2xx w ciągu 10 sekund oznacza ponowienie: do 8 prób z rosnącym odstępem.

  • Ochrona przed powtórzeniem: odrzucaj podpisy starsze niż 5 minut
  • Wymiana sekretu bez przerwy: w okresie przejściowym nagłówek zawiera oba podpisy
  • Historia dostarczeń i ponowne wysłanie jednym kliknięciem
  • article.completedartykuł i jego tłumaczenia są gotowe
  • article.failedzlecenie zakończyło się błędem
  • article.plan_readyplan czeka na zatwierdzenie
  • article.cancelledzlecenie anulowano
  • article.revision_readyrewizja fragmentu jest gotowa
  • ideas.generatednowe pomysły trafiły do projektu
  • project.profile_readyagent skończył analizę strony
  • seo.report_readyraport SEO jest gotowy
Narzędzia

Serwer MCP, walidator i OpenAPI

Serwer MCP

Analiza tonu, czytelności, AI-slop i semantycznego SEO bezpośrednio w Cursor, Claude Desktop i innych klientach MCP. Ten sam token, te same budżety.

"url": "https://app.pennao.com/api/mcp"

Walidator

Kontrola jakości dla tekstów spoza Pennao: LanguageTool, filtr AI-slop, linter SEO, linki i JSON-LD. Wynik w JSON albo jako raport Markdown.

POST /v1/validate

OpenAPI

Opis każdego endpointu w formacie maszynowym. Wygeneruj klienta w swoim języku albo zaimportuj go do Postmana i Insomnii.

GET /api/openapi.json
Tokeny

Token dostaje tylko to, czego potrzebuje

Uprawnienia tokenu to część wspólna jego zakresów i roli osoby, która go utworzyła. Token możesz ograniczyć do wybranych projektów, ustawić mu datę wygaśnięcia i w każdej chwili go unieważnić.

  • articles:readstatusy, treść, wersje, zdarzenia i walidacja
  • articles:writenowe zlecenia, anulowanie, ponowienie, zatwierdzenie planu
  • projects:read / writeprojekty, profile stron i ustawienia
  • ideas:read / writepomysły na tematy i strategie
  • webhooks:read / writewebhooki i historia dostarczeń
  • skills:runanaliza tekstu: ton, czytelność, AI-slop, semantyczne SEO

Twój pierwszy ticket w pięć minut

Załóż konto, dodaj klucz modelu i utwórz token API. Przykłady w curl, Node.js, Pythonie i PHP znajdziesz w dokumentacji.