# Aeneia Signal

> Canonical publication and agent API: https://blog.aeneia.pl. Polish editorial articles cover website design, responsible AI use, East Asian markets and knowledge at work. Other interface languages do not imply translated article bodies.

## Public discovery

- [API guide](https://blog.aeneia.pl/docs/api): authentication, document versions, drafts, publication and retries.
- [OpenAPI 3.1](https://blog.aeneia.pl/openapi.json): machine-readable REST contract.
- [Public feed](https://blog.aeneia.pl/feed.json): published metadata; no API key or draft bodies.
- [Sitemap](https://blog.aeneia.pl/sitemap.xml): canonical public URLs.

## Agent API v1

Use https://blog.aeneia.pl/api/v1 directly. signal.aeneia.pl is a redirecting mirror. Obtain the Bearer key from the human or the server's secret store; never invent, embed, print or publish a key. This server-to-server API accepts no Origin or Cookie headers and provides no browser CORS. The public feed is a separate anonymous resource.

GET /articles lists private drafts and publication snapshots; GET /articles/{slug} returns the current draft and its ETag. POST /articles creates a draft with an Idempotency-Key. PUT /articles/{slug} replaces the draft using If-Match or the current version. POST /articles/{slug}/publish requires the current version, a new Idempotency-Key and Production. GET /media supplies approved cover choices. GET /status compares the requested revision with the fixed public /cms-status.json.

Read the API guide before writing. Preserve the slug. Use saved document metadata plus Markdown body, without frontmatter. A draft save is private; it does not publish. Publication response 202 means the snapshot was accepted, not that the new page is live. Only publication.state=live confirms an observed matching public revision. unknown is inconclusive. Verify the individual public article if its exact content matters.

For an interlinked editorial release, POST /publications with an Idempotency-Key and {"articles":[{"slug":"saved-draft","version":3}]}. Select 1–500 unique saved drafts with their current versions. Validation is atomic across the resulting publication graph; a stale or invalid item prevents the whole release. Unlisted drafts stay private. One shared revision and one leased deploy hook are used. Preserve the same key and slug/version set on retries. Read the API guide for the complete contract.

For create/publish network retries, keep the same Idempotency-Key, accepted document and version for up to 24 hours. A changed operation under the same key returns 409. On 409/412 version conflicts, read and reconcile changes instead of overwriting them. A retryable or interrupted deploy hook can be retried with the original publication key; it does not create a second saved revision. The external build request can be repeated after an ambiguous network failure.

Payload limit: 240000 UTF-8 bytes. Rate limit: 120 requests per IP per 60 seconds, persisted in private Blob with a hashed IP key. Respect Retry-After on 429. There is no permanent delete endpoint. The browser CMS session API remains separate.

Ordered reader recommendations: meta.relatedSlugs positions 0 and 1 select the two highlighted articles; preserve the array order. Publication still needs at least 3 unique related targets and 5 contextual links in body. Optional meta.interludeImage accepts auto (default; normalized to omission), none, or an approved media id. List publishedSummary is public snapshot metadata, never the newer private draft title or body. Read API.md via /docs/api before editing.