docs/api-contracts.md

CarouselForge — API Contracts

All responses follow: { success: boolean, data?: T, error?: string }

---

POST /api/ingest

Accepts raw input and returns extracted content.

Request:

{
  "type": "text" | "url" | "pdf" | "topic",
  "content": "string (text/url/topic) | base64 (pdf)"
}

Response:

{
  "success": true,
  "data": {
    "extracted_text": "...",
    "source_platform": "instagram" | "twitter" | "web" | null,
    "source_url": "..." | null
  }
}

---

POST /api/structure

Sends extracted content to LLM, returns slide structure.

Request:

{
  "content": "extracted text",
  "platform": "instagram" | "threads" | "linkedin",
  "brand_id": 1
}

Response:

{
  "success": true,
  "data": {
    "carousel_id": 42,
    "slides": [...],
    "caption": "...",
    "hashtags": ["#ai", "#tech"]
  }
}

---

POST /api/render

Renders slides to PNG images.

Request:

{ "carousel_id": 42, "template_id": "bold-statement" }

Response:

{
  "success": true,
  "data": {
    "image_paths": ["/tmp/renders/42/1.png", ...],
    "pdf_path": "/tmp/renders/42/carousel.pdf"
  }
}

---

POST /api/publish

Publishes carousel to social platforms.

Request:

{
  "carousel_id": 42,
  "platforms": ["instagram", "threads"],
  "scheduled_for": "2024-01-15T09:00:00Z" | null
}

---

GET /api/analytics

Returns engagement data for published carousels.

---

POST /api/research

Triggers trending topic research for a brand.

Request: { "brand_id": 1 }

---

POST /api/telegram/webhook

Receives Telegram bot updates. Handled by Telegraf internally.

---

POST /api/telegram/notify

Sends a notification to a Telegram user.

Request:

{
  "chat_id": "123456789",
  "type": "carousel_preview" | "publish_confirm" | "daily_brief",
  "payload": { ... }
}

---

Endpoints filled in as phases are completed. See phase guide for full specs.