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:**
```json
{
  "type": "text" | "url" | "pdf" | "topic",
  "content": "string (text/url/topic) | base64 (pdf)"
}
```

**Response:**
```json
{
  "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:**
```json
{
  "content": "extracted text",
  "platform": "instagram" | "threads" | "linkedin",
  "brand_id": 1
}
```

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

---

## POST /api/render
Renders slides to PNG images.

**Request:**
```json
{ "carousel_id": 42, "template_id": "bold-statement" }
```

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "chat_id": "123456789",
  "type": "carousel_preview" | "publish_confirm" | "daily_brief",
  "payload": { ... }
}
```

---

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