{ "openapi": "3.1.0", "info": { "title": "Aeneia Signal Agent API", "version": "1.2.0", "description": "Server-to-server private editorial API. Bearer only; no cookies, Origin or browser CORS. All API responses are no-store. There is no permanent deletion endpoint. Public articles, /feed.json and discovery files are separate anonymous resources. Payload limit 240000 UTF-8 bytes; durable rate limit 120 requests/IP/60s. Respect Retry-After.", "contact": { "url": "https://blog.aeneia.pl/docs/api" } }, "servers": [ { "url": "https://blog.aeneia.pl", "description": "Canonical origin; do not send credentials through the signal.aeneia.pl mirror." } ], "security": [ { "SignalBearer": [] } ], "externalDocs": { "url": "https://blog.aeneia.pl/docs/api", "description": "Draft, ETag, retry and publication workflow" }, "paths": { "/api/v1/articles": { "get": { "operationId": "listArticles", "summary": "List article drafts and saved publication snapshots", "description": "All responses are private and no-store. draft means no published snapshot; published means a saved snapshot, including one whose build is still pending. dirty means the draft differs. Sorted by slug; lists may change between requests.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Query" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "all", "draft", "published", "dirty" ], "default": "all" } }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "Design", "Audit", "Oriens", "Imperium", "Kurs AI" ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Signal-API-Version": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createArticle", "summary": "Create a private draft", "description": "Idempotent creation. Does not publish or invoke a deploy hook. The returned Location points to the authenticated article detail.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "201": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedDraft" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Signal-API-Version": { "schema": { "type": "string" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } }, "Location": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRequest" } } } } } }, "/api/v1/articles/{slug}": { "get": { "operationId": "getArticle", "summary": "Read the saved draft, version and publication snapshot", "description": "", "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Signal-API-Version": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "replaceDraft", "summary": "Replace the complete draft with optimistic concurrency", "description": "Send If-Match or body.version. Missing condition:428; stale If-Match:412; stale body.version:409. Slug is immutable. A saved public snapshot is preserved. No deployment is triggered.", "parameters": [ { "$ref": "#/components/parameters/Slug" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedDraft" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Signal-API-Version": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRequest" } } } } } }, "/api/v1/articles/{slug}/publish": { "post": { "operationId": "publishArticle", "summary": "Validate the saved draft and request publication in Production", "description": "Requires Production and a configured deploy hook. 202 confirms a saved snapshot, not a live page. Check publication.state or GET /status. Same key reuses the same saved revision and may retry an unconfirmed hook. Concurrent dispatch uses a durable lease; an ambiguous external hook receipt can lead to another build of that same snapshot. Validation uses the shared CMS publication gate.", "parameters": [ { "$ref": "#/components/parameters/Slug" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "202": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedPublication" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Signal-API-Version": { "schema": { "type": "string" } }, "Idempotency-Replayed": { "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRequest" } } } } } }, "/api/v1/media": { "get": { "operationId": "listMedia", "summary": "List existing approved cover images", "description": "Read-only library; arbitrary uploads are unavailable. Use url in document.meta.image.", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "$ref": "#/components/parameters/Query" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaList" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Signal-API-Version": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/status": { "get": { "operationId": "publicationStatus", "summary": "Observe pending, live or unknown publication state", "description": "Compares the catalog revision with https://blog.aeneia.pl/cms-status.json only. No redirects, no cache and a bounded timeout. Does not infer a deployment Git SHA. Production may also resume the durable differential SEO outbox once due, only after public manifest/revision validation. SEO failures remain separate from publication.state. Preview never writes or submits. Receipt200/202 does not establish indexing; no independent background wake-up exists.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }, "headers": { "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } }, "Signal-API-Version": { "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/publications": { "post": { "operationId": "publishArticleCollection", "summary": "Atomically publish 1–500 saved article versions in one release", "description": "Production only. Validates the entire resulting publication graph, including links between new drafts. Any invalid or stale article aborts the entire release. One shared revision, one leased deploy hook and one differential SEO outbox. Does not publish unlisted drafts. Retry the same key and exact slug/version set after transport uncertainty; order is immaterial. A 202 response accepts snapshots, not a successful deployment or indexing.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "articles" ], "properties": { "articles": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "slug", "version" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120 }, "version": { "type": "integer", "minimum": 1, "maximum": 999999999 } } } } } } } } }, "responses": { "202": { "description": "Collection snapshots saved atomically; inspect publication.state and seo independently.", "content": { "application/json": { "schema": { "type": "object", "required": [ "revision", "articles", "publication", "seo" ], "properties": { "revision": { "type": "string" }, "acceptedAt": { "type": "string", "format": "date-time" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "version": { "type": "integer" }, "etag": { "type": "string" }, "publicUrl": { "type": "string", "format": "uri" }, "modified": { "type": "string", "format": "date" } } } }, "publication": { "type": "object" }, "seo": { "type": "object" }, "requestId": { "type": "string" } } } } } }, "400": { "description": "Invalid collection, duplicate slug, unsupported field or missing idempotency key." }, "401": { "description": "Missing or invalid Bearer." }, "403": { "description": "Preview environment, browser Origin or Cookie rejected." }, "404": { "description": "A selected draft does not exist." }, "409": { "description": "At least one version is stale, the catalog is busy or the idempotency key belongs to another request. No partial release." }, "422": { "description": "A document failed publication validation. No selected snapshot changed." }, "429": { "description": "Respect Retry-After." }, "503": { "description": "Unavailable hook, storage or idempotency capacity; retry safely." } } } } }, "components": { "securitySchemes": { "SignalBearer": { "type": "http", "scheme": "bearer", "description": "One secret grants read/write/publish. Obtain it out of band and keep it in a server-side secret store. Never put it in a URL or browser client." } }, "parameters": { "Slug": { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "description": "Concrete strong article ETag from GET, e.g. \"v3\". Required unless body.version is supplied. Weak ETags and * are rejected.", "schema": { "type": "string", "pattern": "^\"v[1-9][0-9]{0,8}\"$" } }, "Idempotency": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "One key per intended create/publish operation. Retry the same key and normalized request for 24 hours. Different payload under the same key returns 409.", "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$" } }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "Offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } }, "Query": { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "requestId": { "type": "string" } } }, "Metadata": { "type": "object", "required": [ "slug", "category" ], "description": "Draft metadata may be incomplete. status is forced to draft; unsupported fields are removed by the shared validator. Publication performs the complete editorial checks.", "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120, "description": "Must not be reserved; immutable after creation." }, "category": { "type": "string", "enum": [ "Design", "Audit", "Oriens", "Imperium", "Kurs AI" ] }, "title": { "type": "string", "maxLength": 2500 }, "description": { "type": "string", "maxLength": 2500 }, "intent": { "type": "string", "maxLength": 2500 }, "image": { "type": "string", "maxLength": 2500 }, "imageAlt": { "type": "string", "maxLength": 2500 }, "imagePosition": { "type": "string", "maxLength": 2500 }, "date": { "type": "string", "format": "date" }, "modified": { "type": "string", "format": "date" }, "sourceChecked": { "type": "string", "format": "date" }, "layer": { "type": "string", "enum": [ "design", "audit", "oriens", "kurs-ai" ] }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "Accepted only as input metadata; cleaned draft always has draft status." }, "relatedSlugs": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Ordered related publications. Positions 0 and 1 power the reader rail and recommendations after roughly 1/3 and 2/3 of completed paragraphs. Publication requires at least 3 unique published targets; draft saves may be incomplete." }, "imageWidth": { "type": "integer", "minimum": 1, "maximum": 20000 }, "imageHeight": { "type": "integer", "minimum": 1, "maximum": 20000 }, "responsive": { "type": "boolean" }, "imageLayout": { "type": "string", "enum": [ "native" ] }, "interludeImage": { "type": "string", "maxLength": 80, "description": "Optional midpoint image: auto (default when omitted; normalized to omission on save), none, or an existing approved /media id such as P08. Arbitrary image URLs and uploads are not accepted." } } }, "Document": { "type": "object", "required": [ "meta", "body" ], "properties": { "meta": { "$ref": "#/components/schemas/Metadata" }, "body": { "type": "string", "maxLength": 180000, "description": "Markdown body without JSON frontmatter. The whole HTTP payload is also limited to 240000 UTF-8 bytes." } } }, "CreateRequest": { "type": "object", "additionalProperties": false, "required": [ "document" ], "properties": { "document": { "$ref": "#/components/schemas/Document" } } }, "UpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "document" ], "properties": { "document": { "$ref": "#/components/schemas/Document" }, "version": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "Alternative to If-Match. If both are supplied, they must agree." } } }, "PublishRequest": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1, "maximum": 999999999, "description": "Required when If-Match is absent." } } }, "ArticleSummary": { "type": "object", "required": [ "slug", "title", "category", "version", "etag", "published", "dirty", "publicUrl" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "version": { "type": "integer" }, "etag": { "type": "string" }, "published": { "type": "boolean", "description": "A saved publication snapshot exists; this does not establish that it is live." }, "dirty": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" }, "publicUrl": { "type": "string", "format": "uri" }, "publishedSummary": { "type": "object", "description": "Optional allowlisted metadata from the published snapshot, never from a newer private draft; no article body. Use this to label recommendations.", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "image": { "type": "string" }, "imageAlt": { "type": "string" }, "imageWidth": { "type": "integer" }, "imageHeight": { "type": "integer" }, "imagePosition": { "type": "string" }, "responsive": { "type": "boolean" } } } } }, "Article": { "allOf": [ { "$ref": "#/components/schemas/ArticleSummary" }, { "type": "object", "required": [ "document", "requestId" ], "properties": { "document": { "$ref": "#/components/schemas/Document" }, "publishedDocument": { "oneOf": [ { "$ref": "#/components/schemas/Document" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "title": { "type": "string" } } } }, "requestId": { "type": "string" } } } ] }, "SavedDraft": { "type": "object", "required": [ "slug", "version", "etag", "status", "publicUrl", "requestId" ], "properties": { "slug": { "type": "string" }, "version": { "type": "integer" }, "etag": { "type": "string" }, "status": { "const": "draft" }, "publicUrl": { "type": "string", "format": "uri" }, "requestId": { "type": "string" } } }, "Publication": { "type": "object", "required": [ "state", "requestedRevision", "observedLiveRevision", "observedAt", "delivery" ], "properties": { "state": { "type": "string", "enum": [ "pending", "live", "unknown" ], "description": "live only after the fixed public status URL is observed with the requested revision; unknown is inconclusive." }, "requestedRevision": { "type": "string" }, "observedLiveRevision": { "type": [ "string", "null" ] }, "observedAt": { "type": "string", "format": "date-time" }, "delivery": { "type": "string", "enum": [ "pending", "dispatching", "queued", "retryable", "superseded" ], "description": "Hook delivery only; queued does not mean the publication is live." }, "statusUrl": { "type": "string" } } }, "AcceptedPublication": { "type": "object", "required": [ "slug", "version", "etag", "revision", "publication", "requestId" ], "properties": { "slug": { "type": "string" }, "version": { "type": "integer" }, "etag": { "type": "string" }, "revision": { "type": "string" }, "acceptedAt": { "type": "string", "format": "date-time" }, "publicUrl": { "type": "string", "format": "uri" }, "publication": { "$ref": "#/components/schemas/Publication" }, "requestId": { "type": "string" }, "seo": { "$ref": "#/components/schemas/SeoStatus" }, "modified": { "type": "string", "format": "date", "description": "Authoritative content modification date. Unchanged publication retains the previous date." } } }, "Status": { "type": "object", "required": [ "catalogRevision", "articles", "publication", "requestId" ], "properties": { "catalogRevision": { "type": "string" }, "articles": { "type": "integer" }, "publication": { "$ref": "#/components/schemas/Publication" }, "requestId": { "type": "string" }, "seo": { "$ref": "#/components/schemas/SeoStatus" } } }, "MediaItem": { "type": "object", "required": [ "id", "title", "alt", "url", "width", "height" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "alt": { "type": "string" }, "url": { "type": "string", "description": "Relative /images path to use in document.meta.image." }, "width": { "type": "integer" }, "height": { "type": "integer" }, "focus": { "type": "array", "items": { "type": "number" } } } }, "ArticleList": { "type": "object", "required": [ "items", "total", "limit", "offset", "nextOffset", "requestId" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ArticleSummary" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] }, "requestId": { "type": "string" }, "catalogRevision": { "type": "string" } } }, "MediaList": { "type": "object", "required": [ "items", "total", "limit", "offset", "nextOffset", "requestId" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MediaItem" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] }, "requestId": { "type": "string" } } }, "SeoStatus": { "type": "object", "description": "Separate durable notification state. pending is not content publication state.200/202 receipts never establish indexing. Preview is disabled. nextDue requires another authenticated status/panel/gate request; no background scheduler.", "required": [ "state", "pending", "nextDue", "indexingConfirmed" ], "properties": { "state": { "type": "string" }, "pending": { "type": "boolean" }, "nextDue": { "type": [ "integer", "null" ], "description": "Unix milliseconds; null means manual preparation/recovery is required." }, "keyValidationPending": { "type": "boolean" }, "pendingUrls": { "type": "integer" }, "acceptedRevision": { "type": [ "string", "null" ] }, "lastReceipt": { "type": [ "object", "null" ] }, "indexingConfirmed": { "type": "boolean", "const": false }, "wakeUp": { "type": "string" } } } }, "responses": { "Error": { "description": "400 invalid input;401 missing/invalid Bearer;403 Origin/Cookie/Production policy;404 missing;405 unavailable method;409 conflict;412 stale If-Match;413 size;415 content type;422 publication validation;428 missing version;429 rate limit;503 unavailable. Errors contain no credentials or provider details.", "headers": { "Retry-After": { "schema": { "type": "string" } }, "WWW-Authenticate": { "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } }, "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }