> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yalg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YALG blog integration

> Receive finished YALG blog posts automatically in your client application.

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.

<Note>
  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.
</Note>

## 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.

```http theme={null}
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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```text theme={null}
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.