# Agent publishing API

Base URL: `https://anwarpy.ai/api/agent/posts`

Authentication: send the current secret in `x-agent-key`. The key is stored only in the deployment environment and the local secret store; it must not appear in source, logs, prompts, or this document.

## Create

`POST /api/agent/posts`

```json
{
  "title": "دليل عربي",
  "slug": "arabic-ai-guide",
  "dek": "وصف عملي",
  "teaser": "مطلوب لمقال VIP فقط",
  "content": { "root": { "type": "root", "children": [] } },
  "category": "أدوات",
  "access": "vip",
  "readingMinutes": 7,
  "publish": true,
  "coverImage": {
    "filename": "arabic-ai-guide.jpg",
    "dataBase64": "<raw JPEG base64>"
  }
}
```

Rules:

- `slug`: lowercase ASCII kebab-case.
- `category`: one of `وكلاء`, `نماذج`, `استرجاع`, `سلامة`, `أدوات`, `أعمال`.
- `access`: `free` or `vip`.
- VIP requires a non-empty teaser.
- `coverImage` is optional. When provided it must be JPEG and no larger than 5MB. Otherwise the seeded category cover is used.
- `publish` omitted or false creates `status=draft`; true creates `status=published` with a server timestamp.
- Unknown fields, including direct `status`, `publishedAt`, and `level`, return 400.
- An existing or racing duplicate slug returns 409.

Success: 201.

## Lookup

`GET /api/agent/posts/<slug>`

Returns 200 for a draft or published post, 404 when absent. Authentication is required. The response never includes article or teaser content.

## Promote or republish

`PATCH /api/agent/posts/<slug>`

Draft promotion body:

```json
{ "publish": true }
```

A full republish uses the same body as create, requires `publish=true`, and requires the body slug to match the URL slug. It updates the existing post and never creates a second slug.

## Response

```json
{
  "id": 42,
  "title": "دليل عربي",
  "slug": "arabic-ai-guide",
  "status": "published",
  "access": "vip",
  "category": "أدوات",
  "publishedAt": "2026-10-09T12:00:00.000Z",
  "url": "https://anwarpy.ai/posts/arabic-ai-guide"
}
```

Canonical URLs have no `www` and no trailing slash.