API

Calendar & Images API

Editorial-Calendar-Events sowie AI-Image-Generation, -Gallery und -Edits per HTTP.

Zwei eng verwandte Subsysteme: der Editorial Calendar plant geplante Veröffentlichungen pro Projekt, die Image Gallery verwaltet team-weit alle generierten Bilder. Beide arbeiten mit Articles zusammen — ein Calendar-Event referenziert oft einen Artikel, ein Bild wird oft direkt aus einem Artikel-Hero-Slot heraus generiert.

Modul-Kontext: Editorial Calendar · Image Gallery.

Calendar

Pro Projekt eine eigene Event-Liste, jede Event ist ein geplanter Content-Slot (Artikel, Social-Post, Newsletter etc.).

Method	Endpoint	Beschreibung
GET	`/v1/projects/{project}/calendar`	Alle Events des Projekts
POST	`/v1/projects/{project}/calendar`	Neues Event anlegen
GET	`/v1/calendar/{id}`	Detail
PUT	`/v1/calendar/{id}`	Update (`title`, `scheduled_at`, `status`, `article_id`)
DELETE	`/v1/calendar/{id}`	Löschen

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-Projekt-Listing — bleibt aus Kompatibilitätsgründen erhalten. Für neue Integrationen die team-weite Gallery unten nutzen.

Method	Endpoint	Beschreibung
GET	`/v1/projects/{project}/images`	Bilder eines Projekts (legacy)

Image Gallery (team-scoped, primärer Pfad)

Cross-Team-IDs liefern 404 (kein Existenz-Leak, kein 403).

Lesen & Filtern

Method	Endpoint	Beschreibung
GET	`/v1/images`	Filter: `?q`, `?model`, `?from`, `?to`, `?favorite`, `?tags[]`, `?sort=newest\|oldest\|edited`, `?page`, `?per_page`
GET	`/v1/images/trash`	Soft-deleted Bilder
GET	`/v1/images/{id}`	Detail inkl. `variants[]` und `parent`-Tree

Erzeugen & Bearbeiten

Method	Endpoint	Credits	Beschreibung
POST	`/v1/generate/image`	5	Neues Bild aus Prompt erzeugen (async)
POST	`/v1/images/{id}/edit`	10	Edit-Variante via OpenAI `/v1/images/edits`. Async 202 → `{job_id, edit_session_id}`
PATCH	`/v1/images/{id}`	0	Metadaten: `{title?, tags?[]}`
POST	`/v1/images/{id}/favorite`	0	Toggle `is_favorite`

# Edit dispatchen
curl -X POST "$BASE/images/42/edit" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"prompt":"same scene, golden hour lighting"}'

# Pollen bis edit fertig — neue Variante taucht in variants[] auf
curl "$BASE/images/42" -H "Authorization: Bearer $TOKEN" \
  | jq '.data.variants[-1] | {id, processing_status, url}'

Trash & Bulk

Method	Endpoint	Beschreibung
DELETE	`/v1/images/{id}`	Soft-delete (30 Tage Trash, dann hard-delete)
POST	`/v1/images/{id}/restore`	Aus Trash wiederherstellen
DELETE	`/v1/images/{id}/forever`	Endgültig löschen — NUR aus Trash, sonst `409`
POST	`/v1/images/bulk/delete`	Body `{ids:[]}` max 200
POST	`/v1/images/bulk/restore`	Body `{ids:[]}` max 200
POST	`/v1/images/bulk/export`	Body `{ids:[]}` max 500. Async 202 → `{job_id}` (ZIP)
GET	`/v1/images/exports/{job_id}`	Export-Status: `{status, download_url?}`

Sharing & Chat

Method	Endpoint	Beschreibung
POST	`/v1/images/{id}/open-in-chat`	Erstellt `AiChatSession` mit `gallery_image_id={id}` → `{session_id}`
POST	`/v1/images/{id}/share`	Idempotenter Public-Share. Body `{expires_at?}` → `{token, public_url, …}`
PATCH	`/v1/images/{id}/share`	Expiry ändern. `{expires_at: ISO\|null}` (404 wenn kein aktiver Share)
DELETE	`/v1/images/{id}/share`	Public-Share widerrufen (View-Count bleibt)

Hinweise

Image-Generate ist async. POST /v1/generate/image liefert 202 mit Job-ID — GET /v1/images/{id} bis processing_status == "ready" pollen.
Edit erzeugt Variante, kein Replace. Das Original bleibt erhalten; die neue Variante hängt am parent-Tree.
Bulk-Limits sind hart. bulk/delete und bulk/restore sind auf 200 IDs gedeckelt, bulk/export auf 500. Größere Sets in Tranchen schicken.
Gallery ist team-scoped. Cross-Team-Zugriff ergibt 404 (per Design — keine Existenz-Leaks).

Verwandt: Artikel-API · Calendar · Image Gallery.

Letzte Aktualisierung: 1. Mai 2026