Developers

Articles as part of your own system

A REST API described with OpenAPI, webhooks signed with HMAC and an MCP server. Everything you do in the dashboard, you can do from code.

Quick start

From token to published text in three steps

  1. 1

    Create a token

    In Settings → API tokens choose scopes and projects. The token starts with psk_live_ and is shown only once.

  2. 2

    Order an article

    Send a brief with an Idempotency-Key header. The 202 response holds a ticket and links to the status, content and events.

  3. 3

    Receive the webhook

    When it is done, Pennao sends article.completed with the quality score, cost and a link to the content.

order.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": "Is a home battery worth it with solar?",
      "keywords": { "primary": "home battery with solar" },
      "intent": "commercial"
    },
    "settings": { "languages": ["en", "de", "nl"], "includeFaq": true }
  }'

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

The endpoints you will use most

Errors in application/problem+json, cursor pagination and rate limits returned as 429 with Retry-After. The full list is in the interactive reference.

POST /v1/articles new order, 202 response with a ticket
GET /v1/articles/{ticket} status, stage, progress, cost and quality score
GET /v1/articles/{ticket}/events live progress (Server-Sent Events)
GET /v1/articles/{ticket}/content Markdown, HTML or JSON in the chosen language
POST /v1/articles/{ticket}/approve-plan approve the plan before writing
POST /v1/articles/{ticket}/translations new language versions of a finished text
POST /v1/validate quality check of any text
POST /v1/webhooks new webhook with a signing secret
Webhooks

Events your system can react to

Every delivery carries a Pennao-Signature header with an HMAC-SHA256 signature and a timestamp. Anything other than 2xx within 10 seconds means a retry: up to 8 attempts with a growing delay.

  • Replay protection: reject signatures older than 5 minutes
  • Secret rotation without downtime: during the switch the header carries both signatures
  • Delivery history and one-click redelivery
  • article.completedthe article and its translations are ready
  • article.failedthe order ended with an error
  • article.plan_readythe plan is waiting for approval
  • article.cancelledthe order was cancelled
  • article.revision_readya passage revision is ready
  • ideas.generatednew ideas reached a project
  • project.profile_readythe agent finished analyzing a site
  • seo.report_readyan SEO report is ready
Tools

MCP server, validator and OpenAPI

MCP server

Tone, readability, AI-slop and semantic SEO analysis right in Cursor, Claude Desktop and other MCP clients. Same token, same budgets.

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

Validator

Quality checks for text written outside Pennao: LanguageTool, the AI-slop filter, an SEO linter, links and JSON-LD. Results as JSON or a Markdown report.

POST /v1/validate

OpenAPI

A machine-readable description of every endpoint. Generate a client in your language or import it into Postman and Insomnia.

GET /api/openapi.json
Tokens

A token gets only what it needs

A token’s permissions are the intersection of its scopes and the role of the person who created it. Limit a token to selected projects, set an expiry date and revoke it at any time.

  • articles:readstatuses, content, versions, events and validation
  • articles:writenew orders, cancel, retry, approve the plan
  • projects:read / writeprojects, site profiles and settings
  • ideas:read / writetopic ideas and strategies
  • webhooks:read / writewebhooks and delivery history
  • skills:runtext analysis: tone, readability, AI-slop, semantic SEO

Your first ticket in five minutes

Create an account, add a model key and create an API token. Examples in curl, Node.js, Python and PHP are in the documentation.