76 lines
2.1 KiB
Markdown
76 lines
2.1 KiB
Markdown
# 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
|
|
|
|
`PUT /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.
|