Publish API contract 1.0

HTTP request

The engine sends one POST per article. There is no HMAC, signature, or timestamp header.

POST {your-ingest-url}
Content-Type: application/json
Authorization: Bearer {destination-secret}
X-Idempotency-Key: {32-char-hex-article-id}

Authentication

• Bearer only. Compare the token with a fixed-time equals.
• Missing, wrong scheme, or wrong secret: 401 with { "error": "..." }.
• Do not accept query-string secrets, Basic auth, or unsigned requests.

JSON payload

Root object, camelCase, schemaVersion always 1.0. Unknown properties should be ignored so later additive fields do not break you.

{
  schemaVersion,      // "1.0"
  idempotencyKey,     // 32-char hex, same as X-Idempotency-Key
  publishedAt,        // ISO-8601 with offset, e.g. 2026-08-22T16:00:00.0000000+00:00
  offering:  { id, name, category, subcategory, ctaUrl },
  article:   { id, title, slug, summary, bodyHtml },
  seo:       { metaTitle, metaDescription, canonicalPath, robots, keywords, imageRole, openGraph, twitter },
  jsonLd:    { Article + ImageObject + citations },
  images:    [ { role, alt, caption, contentType, bytesBase64 } ],
  sources:   [ { label, url } ]
}

Minimum fields this stand-in validates: article.title and article.slug. Implement the full object anyway. Production articles always send every key above.

Field reference

Root

offering

article

seo

jsonLd

Ready-to-emit schema.org Article. Put it in <script type="application/ld+json"> after you fill image.contentUrl and turn path fields into absolute URLs.

images[]

The array may be empty. Only images with bytes are included.

sources[]

bodyHtml rules

article.bodyHtml is the inner HTML of the page. Wrap it yourself:

<article>
  {bodyHtml}
</article>

The engine already:

• Converts markdown to HTML unless the body already looks like HTML (starts with < and contains >).
• Strips wrapping <article> tags and a leading markdown # title.
• Prepends a <header> (optional kicker, <h1>, optional summary, <time>) only when no <h1> exists.
• Injects missing role figures: hero before the body, other roles after. <img src=""> is intentional.
• Appends <section id="sources"> when sources exist and the body does not already have one.
• Appends one Learn more CTA (p.cms-cta) when offering.ctaUrl is set and not already in the HTML.
• Appends p.cms-disclaimer only when the offering has a disclaimer.

You may style .kicker, .summary, .cms-cta, .cms-disclaimer, and #sources. Do not strip them.

Images and URL rewrite

Image URL slots stay null on the wire so you can assign your own public URLs.

1. For each images[] entry, decode bytesBase64 and store it (use contentType for the extension).
2. Set seo.openGraph["og:image"], seo.twitter["twitter:image"], and jsonLd.image.contentUrl to that public URL (hero / first image).
3. Replace empty src="" on matching data-image-role images in bodyHtml with the same URL.

Figures look like:

<figure data-image-role="hero">
  <img data-image-role="hero" src="" alt="...">
  <figcaption>...</figcaption>
</figure>

Responses you must return

The engine treats any 2xx as delivered. If the body is JSON it reads optional id and url for the delivery ledger.

Five failed attempts or an oversize payload marks the engine delivery dead. Do not return 2xx unless the article is stored and publishable.

Implementation checklist

1. Expose POST at the URL you give ServAEO (HTTPS in production).
2. Require Authorization: Bearer {secret} with a fixed-time compare. Reject others with 401.
3. Read X-Idempotency-Key. Upsert by that key. First write 201, later writes 200 with replayed: true.
4. If Content-Encoding: gzip, inflate before parsing JSON.
5. Reject bodies over your size cap with 413.
6. Parse JSON. Require article.title and article.slug or return 422.
7. Persist the full payload (or the fields you render).
8. Decode images[].bytesBase64, store files, rewrite image URL slots and empty src="".
9. Publish at https://{host}{seo.canonicalPath}.
10. Emit <title>, description, robots, canonical, Open Graph, Twitter, and JSON-LD. Prefix site-relative paths with your host.
11. Render <article>{bodyHtml}</article>. Do not wrap a second <article> if you already have one in your template around the injection point only.
12. Return JSON with id and public url on success.

Complete sample

This is a full 1.0 POST body, including a 1x1 PNG in bytesBase64. Real images are larger. Open raw JSON.

{
  "schemaVersion": "1.0",
  "idempotencyKey": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "publishedAt": "2026-08-22T16:00:00.0000000+00:00",
  "offering": {
    "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "name": "Sample offering",
    "category": "HVAC",
    "subcategory": "Heat pumps",
    "ctaUrl": "https://example.com/learn"
  },
  "article": {
    "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "title": "How does a heat pump work?",
    "slug": "how-does-a-heat-pump-work",
    "summary": "A heat pump moves heat rather than generating it.",
    "bodyHtml": "<header><p class=\"kicker\">Sample offering</p><h1>How does a heat pump work?</h1><p class=\"summary\">A heat pump moves heat rather than generating it.</p><time datetime=\"2026-08-22T16:00:00.0000000+00:00\">2026-08-22</time></header><figure data-image-role=\"hero\"><img data-image-role=\"hero\" src=\"\" alt=\"A heat pump outdoor unit\"><figcaption>Typical air-source heat pump</figcaption></figure><p>A heat pump moves heat from one place to another.</p>\n<h2>Key takeaways</h2>\n<ul>\n<li>It transfers heat</li>\n<li>It can heat or cool</li>\n</ul>\n<h2>FAQ</h2>\n<p><strong>What is a heat pump?</strong> A device that moves heat.</p><section id=\"sources\"><h2>Sources</h2><ol><li><a href=\"https://example.com/doe-heat-pumps\" rel=\"nofollow noopener\">DOE heat pumps</a></li></ol></section><p class=\"cms-cta\"><a href=\"https://example.com/learn\">Learn more</a></p>"
  },
  "seo": {
    "metaTitle": "How does a heat pump work?",
    "metaDescription": "A heat pump moves heat rather than generating it.",
    "canonicalPath": "/answers/how-does-a-heat-pump-work",
    "robots": "index,follow",
    "keywords": ["heat pump", "HVAC"],
    "imageRole": "hero",
    "openGraph": {
      "og:type": "article",
      "og:title": "How does a heat pump work?",
      "og:description": "A heat pump moves heat rather than generating it.",
      "og:site_name": "Sample offering",
      "og:url": "/answers/how-does-a-heat-pump-work",
      "og:locale": "en_US",
      "article:published_time": "2026-08-22T16:00:00.0000000+00:00",
      "article:modified_time": "2026-08-22T16:00:00.0000000+00:00",
      "article:section": "Heat pumps",
      "og:image": null,
      "og:image:alt": "A heat pump outdoor unit",
      "og:image:type": "image/png"
    },
    "twitter": {
      "twitter:card": "summary_large_image",
      "twitter:title": "How does a heat pump work?",
      "twitter:description": "A heat pump moves heat rather than generating it.",
      "twitter:image": null,
      "twitter:image:alt": "A heat pump outdoor unit"
    }
  },
  "jsonLd": {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "How does a heat pump work?",
    "name": "How does a heat pump work?",
    "url": "/answers/how-does-a-heat-pump-work",
    "inLanguage": "en-US",
    "isAccessibleForFree": true,
    "datePublished": "2026-08-22T16:00:00.0000000+00:00",
    "dateModified": "2026-08-22T16:00:00.0000000+00:00",
    "description": "A heat pump moves heat rather than generating it.",
    "keywords": "heat pump, HVAC",
    "publisher": {
      "@type": "Organization",
      "name": "Sample offering"
    },
    "mainEntityOfPage": {
      "@type": "WebPage",
      "@id": "/answers/how-does-a-heat-pump-work"
    },
    "image": {
      "@type": "ImageObject",
      "contentUrl": null,
      "name": "A heat pump outdoor unit",
      "caption": "Typical air-source heat pump",
      "encodingFormat": "image/png",
      "representativeOfPage": true,
      "role": "hero"
    },
    "citation": [
      {
        "@type": "CreativeWork",
        "name": "DOE heat pumps",
        "url": "https://example.com/doe-heat-pumps"
      }
    ]
  },
  "images": [
    {
      "role": "hero",
      "alt": "A heat pump outdoor unit",
      "caption": "Typical air-source heat pump",
      "contentType": "image/png",
      "bytesBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
    }
  ],
  "sources": [
    {
      "label": "DOE heat pumps",
      "url": "https://example.com/doe-heat-pumps"
    }
  ]
}