Calendar & Images API
Editorial calendar events plus AI image generation, gallery, and edits over HTTP.
Two closely related sub-systems: the Editorial Calendar schedules planned publications per project, the Image Gallery manages all generated images team-wide. Both work together with articles — a calendar event often references an article, an image is often generated directly from an article hero slot.
Module context: Editorial Calendar · Image Gallery.
Calendar
One event list per project; each event is a planned content slot (article, social post, newsletter, etc.).
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/projects/{project}/calendar |
All events of the project |
| POST | /v1/projects/{project}/calendar |
Create new event |
| GET | /v1/calendar/{id} |
Detail |
| PUT | /v1/calendar/{id} |
Update (title, scheduled_at, status, article_id) |
| DELETE | /v1/calendar/{id} |
Delete |
curl -X POST "$BASE/projects/12/calendar" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"title": "AI Coding Tools — Launch Post",
"scheduled_at": "2026-05-15T09:00:00Z",
"article_id": 88,
"status": "scheduled"
}'
Project Images (legacy)
Per-project listing — kept for compatibility. For new integrations use the team-wide gallery below.
| Method | Endpoint | Description |
|---|---|---|
| GET | /v1/projects/{project}/images |
Images of one project (legacy) |
Image Gallery (team-scoped, primary path)
Cross-team IDs return 404 (no existence leak, no 403).
Read & filter
| Method | Endpoint | Credits | Description |
|---|---|---|---|
| GET | /v1/images |
0 | Filters: ?q, ?model, ?from, ?to, ?favorite, ?tags[], ?sort=newest|oldest|edited, ?page, ?per_page |
| GET | /v1/images/trash |
0 | Soft-deleted images |
| GET | /v1/images/{id} |
0 | Detail including variants[] and parent tree |
Create & edit
| Method | Endpoint | Credits | Description |
|---|---|---|---|
| POST | /v1/generate/image |
5 | Generate new image from a prompt (async) |
| POST | /v1/images/{id}/edit |
10 | Edit variant via OpenAI /v1/images/edits. Async 202 → {job_id, edit_session_id} |
| PATCH | /v1/images/{id} |
0 | Metadata: {title?, tags?[]} |
| POST | /v1/images/{id}/favorite |
0 | Toggle is_favorite |
# Dispatch edit
curl -X POST "$BASE/images/42/edit" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"prompt":"same scene, golden hour lighting"}'
# Poll until edit is done — new variant shows up in variants[]
curl "$BASE/images/42" -H "Authorization: Bearer $TOKEN" \
| jq '.data.variants[-1] | {id, processing_status, url}'
Trash & bulk
| Method | Endpoint | Credits | Description |
|---|---|---|---|
| DELETE | /v1/images/{id} |
0 | Soft-delete (30 days trash, then hard-delete) |
| POST | /v1/images/{id}/restore |
0 | Restore from trash |
| DELETE | /v1/images/{id}/forever |
0 | Permanently delete — only from trash, otherwise 409 |
| POST | /v1/images/bulk/delete |
0 | Body {ids:[]} max 200 |
| POST | /v1/images/bulk/restore |
0 | Body {ids:[]} max 200 |
| POST | /v1/images/bulk/export |
0 | Body {ids:[]} max 500. Async 202 → {job_id} (ZIP) |
| GET | /v1/images/exports/{job_id} |
0 | Export status: {status, download_url?} |
Sharing & chat
| Method | Endpoint | Credits | Description |
|---|---|---|---|
| POST | /v1/images/{id}/open-in-chat |
0 | Creates AiChatSession with gallery_image_id={id} → {session_id} |
| POST | /v1/images/{id}/share |
0 | Idempotent public share. Body {expires_at?} → {token, public_url, …} |
| PATCH | /v1/images/{id}/share |
0 | Change expiry. {expires_at: ISO|null} (404 if no active share) |
| DELETE | /v1/images/{id}/share |
0 | Revoke public share (view count is preserved) |
Notes
- Image generate is async.
POST /v1/generate/imagereturns202with a job ID — pollGET /v1/images/{id}untilprocessing_status == "ready". - Edit creates a variant, no replace. The original is preserved; the new variant attaches to the
parenttree. - Bulk limits are hard.
bulk/deleteandbulk/restoreare capped at 200 IDs,bulk/exportat 500. Send larger sets in chunks. - Gallery is team-scoped. Cross-team access returns
404(by design — no existence leaks).
Related: Articles API · Calendar · Image Gallery.
Letzte Aktualisierung: May 1, 2026