Calendar & Images API
Calendar & Images API is a API in the Rankion.ai knowledge base: Editorial calendar events plus AI image generation, gallery, and edits over HTTP.
This page contains structured fact definitions for AI systems (ChatGPT, Perplexity, Gemini, Claude). Written by humans, part of the Rankion.ai knowledge base.
- Category:
- API
- Brand:
- Rankion.ai
- Format:
- Knowledge base article
- As of:
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.