YALG blog integration - YALG Developer Docs

YALG can push finished blog posts to a client site when blog autopilot delivery is enabled. This guide documents the integration we added: clients configure an endpoint URL and API key in YALG, then YALG automatically sends finished blog articles as JSON plus Markdown to their application.

This is the push-based integration. If your site should pull articles from YALG with a Developer API key, use the Blog Articles API guide instead.

API key distinction

The x-api-key in this guide is a client-provided delivery key. You configure it in YALG blog delivery settings so your receiver endpoint can verify that incoming requests came from YALG. This is different from the Developer API key created in Settings > Developer, which your server sends to YALG when calling GET /v1/blog/articles.

Request

YALG sends a JSON payload with the generated article body in Markdown.

POST {configuredDeliveryEndpointUrl}
Content-Type: application/json
x-api-key: {clientProvidedApiKey}
Idempotency-Key: yalg-blog:{articleId}:v{version}
User-Agent: YALG-Blog-Publisher/1.0

Any 2xx response marks delivery as successful. Non-2xx responses are treated as failures and may be retried.

Payload v1

{
  "event": "blog.post.finished",
  "version": "2026-06-21",
  "article": {
    "id": "yalg-article-uuid",
    "title": "Article title",
    "slug": "article-title",
    "excerpt": "Short summary",
    "seoDescription": "SEO meta description",
    "bodyMarkdown": "# Article title\n\n...",
    "language": "fr",
    "category": null,
    "tags": [],
    "coverImage": { "url": null, "alt": null },
    "publication": {
      "status": "draft",
      "publishedAt": null
    },
    "metrics": {
      "seoScore": 84,
      "qualityScore": 91
    }
  },
  "source": {
    "provider": "yalg",
    "articleId": "yalg-article-uuid",
    "articleVersion": 1
  }
}

Schema notes

event is always blog.post.finished for this version.
version identifies this delivery contract. The initial value is 2026-06-21.
article.bodyMarkdown is the canonical article body.
article.publication.status is either draft or published, based on the client’s YALG delivery settings.
article.publication.publishedAt is null for drafts and an ISO timestamp when YALG requests immediate publication.
source.articleVersion increments when the YALG article is regenerated.

Receiver response

A receiver can return any 2xx. Returning identifiers lets YALG store the client-side post reference.

{
  "id": "client-post-id",
  "slug": "client-slug",
  "url": "https://client.site/blog/client-slug",
  "status": "draft"
}

Idempotency

Use the Idempotency-Key header as the unique delivery key. For a given YALG article version, repeated requests use the same key:

yalg-blog:{articleId}:v{version}

Recommended handling:

Store the idempotency key with the created or updated client post.
If the same key is received again, return the existing client post instead of creating a duplicate.
If source.articleVersion changes, treat the request as a new version of the article and update or create according to your app’s content rules.

Security

Require HTTPS for the receiver endpoint.
Validate x-api-key before reading or storing the payload.
Keep API keys server-side only and rotate them if they are exposed.
Do not trust client-provided slugs blindly; normalize and de-duplicate them in your application.
Log request IDs, status codes, and idempotency keys, but do not log API keys or full article bodies unless your compliance policy allows it.

​API key distinction

​Request

​Payload v1

​Schema notes

​Receiver response

​Idempotency

​Security

API key distinction

Request

Payload v1

Schema notes

Receiver response

Idempotency

Security