### Start Open Carrusel with Claude Code

Source: https://github.com/hainrixz/open-carrusel/blob/main/README.md

After cloning and navigating to the Open Carrusel directory, this command initiates the application within Claude Code. The AI will then guide you through the setup.

```bash
/start
```

--------------------------------

### Manual Setup and Development Server for Open Carrusel

Source: https://github.com/hainrixz/open-carrusel/blob/main/README.md

This sequence manually sets up dependencies, seeds data, and starts the development server for Open Carrusel. This method allows using the editor and export features but requires separate AI integration if needed.

```bash
git clone https://github.com/Hainrixz/open-carrusel.git
cd open-carrusel
npm run setup        # installs deps + seeds /data/
npm run dev          # starts http://localhost:3000
```

--------------------------------

### Clone and Run Open Carrusel with Claude Code

Source: https://github.com/hainrixz/open-carrusel/blob/main/README.md

This command sequence clones the repository, navigates into the directory, and starts the application using Claude Code for AI integration. Ensure Claude Code is installed and authenticated first.

```bash
git clone https://github.com/Hainrixz/open-carrusel.git
cd open-carrusel
claude
```

--------------------------------

### Run Development and Setup Commands

Source: https://github.com/hainrixz/open-carrusel/blob/main/README.md

Standard npm scripts for managing the development environment and project lifecycle.

```bash
npm run setup     # equivalent to /start (skips the browser-open + background server bits)
npm run dev       # start the dev server
npm run build     # production build
npm run doctor    # run scripts/doctor.mjs (works pre-`npm install`)
```

--------------------------------

### GET /api/chat/check

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Verifies that the Claude CLI is installed and accessible.

```APIDOC
## GET /api/chat/check

### Description
Verifies that the Claude CLI is installed and accessible.

### Method
GET

### Endpoint
/api/chat/check

### Response
#### Success Response (200)
- **available** (boolean) - Indicates if the CLI is available
- **path** (string) - The file path to the CLI executable

#### Response Example
{
  "available": true,
  "path": "/usr/local/bin/claude"
}
```

--------------------------------

### Example Chat Interaction

Source: https://github.com/hainrixz/open-carrusel/blob/main/README.md

Demonstrates the conversational flow between the user and the Claude agent for generating and editing carousel slides.

```text
You    > Create a 5-slide carousel about “3 morning habits that
         actually move the needle.” Punchy, dark mode, accent red,
         portrait 4:5.

Claude > Coming up. I'll build a hook slide, three habit slides,
         and a CTA. Working...
         [streams 5 HTML slides into the filmstrip]

You    > Slide 3 — the headline is too long. Cut it in half and
         move the icon to the top.

Claude > Done.
         [updates that slide; you can /undo if you preferred the old one]
```

--------------------------------

### GET /api/fonts

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Lists available Google Fonts.

```APIDOC
## GET /api/fonts

### Description
Returns a curated list of Google Fonts optimized for social media carousels.

### Method
GET

### Endpoint
/api/fonts
```

--------------------------------

### Get Brand Configuration

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Retrieves the current brand identity settings, including colors, fonts, logo path, and style keywords. This information is used by Claude for generating slides with a consistent brand appearance.

```bash
# Get brand config
curl -s http://localhost:3000/api/brand
```

```json
# Response:
{
  "name": "My Brand",
  "colors": {
    "primary": "#1a1a2e",
    "secondary": "#16213e",
    "accent": "#e94560",
    "background": "#ffffff",
    "surface": "#f5f5f5"
  },
  "fonts": {
    "heading": "Playfair Display",
    "body": "Inter"
  },
  "customFonts": [],
  "logoPath": "/uploads/logo.png",
  "styleKeywords": ["minimal", "editorial", "bold typography"],
  "createdAt": "2024-01-10T08:00:00.000Z",
  "updatedAt": "2024-01-15T09:00:00.000Z"
}
```

--------------------------------

### GET /api/brand

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Returns the current brand identity settings including colors, fonts, logo, and style keywords.

```APIDOC
## GET /api/brand

### Description
Returns the current brand identity settings including colors, fonts, logo, and style keywords that Claude uses for slide generation.

### Method
GET

### Endpoint
/api/brand

### Response
#### Success Response (200)
- **name** (string) - Brand name
- **colors** (object) - Color palette
- **fonts** (object) - Font settings
- **logoPath** (string) - Path to logo
- **styleKeywords** (array) - List of style keywords

#### Response Example
{
  "name": "My Brand",
  "colors": {
    "primary": "#1a1a2e",
    "secondary": "#16213e",
    "accent": "#e94560",
    "background": "#ffffff",
    "surface": "#f5f5f5"
  },
  "fonts": {
    "heading": "Playfair Display",
    "body": "Inter"
  },
  "logoPath": "/uploads/logo.png",
  "styleKeywords": ["minimal", "editorial", "bold typography"]
}
```

--------------------------------

### Check Claude CLI Availability

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Verifies that the Claude CLI is installed and accessible by making a request to the local API endpoint. This is useful for ensuring the environment is set up correctly before proceeding with other operations.

```bash
# Check if Claude CLI is available
curl -s http://localhost:3000/api/chat/check
```

```json
# Response (success):
{ "available": true, "path": "/usr/local/bin/claude" }
```

```json
# Response (not found):
{ "available": false, "error": "Claude CLI not found" }
```

--------------------------------

### GET /api/templates

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Returns all saved carousel templates.

```APIDOC
## GET /api/templates

### Description
Returns all saved carousel templates.

### Method
GET

### Endpoint
/api/templates

### Response
#### Success Response (200)
- **templates** (array) - List of template objects
```

--------------------------------

### Get a Single Carousel

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Fetches detailed information for a specific carousel, including its slide content.

```bash
# Get carousel by ID
curl -s http://localhost:3000/api/carousels/xyz789

# Response:
{
  "id": "xyz789",
  "name": "5 Morning Habits That Changed My Life",
  "aspectRatio": "4:5",
  "slides": [
    {
      "id": "slide1",
      "html": "<div style=\"width: 1080px; height: 1350px; ...\">...</div>",
      "previousVersions": [],
      "order": 0,
      "notes": "Hook slide"
    }
  ],
  "referenceImages": [],
  "caption": "Transform your mornings...",
  "hashtags": ["productivity", "morninghabits"],
  "chatSessionId": "session_abc",
  "isTemplate": false,
  "tags": [],
  "createdAt": "2024-01-15T10:35:00.000Z",
  "updatedAt": "2024-01-15T11:00:00.000Z"
}
```

--------------------------------

### Get Reference Images

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Lists all reference images attached to a carousel. These images are used by Claude for style analysis to replicate visual styles in generated slides.

```bash
# Get reference images for carousel
curl -s http://localhost:3000/api/carousels/xyz789/references
```

```json
# Response:
{
  "references": [
    {
      "id": "ref_001",
      "url": "/uploads/reference-carousel.png",
      "absPath": "/app/public/uploads/reference-carousel.png",
      "name": "Competitor carousel style",
      "addedAt": "2024-01-15T10:00:00.000Z"
    }
  ]
}
```

--------------------------------

### GET /api/carousels

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Retrieves a list of all carousel projects stored locally, excluding templates.

```APIDOC
## GET /api/carousels

### Description
Returns all carousel projects stored locally, excluding templates.

### Method
GET

### Endpoint
/api/carousels

### Response
#### Success Response (200)
- **carousels** (array) - List of carousel objects

#### Response Example
{
  "carousels": [
    {
      "id": "abc123",
      "name": "Morning Habits",
      "aspectRatio": "4:5",
      "slides": [],
      "referenceImages": [],
      "chatSessionId": null,
      "isTemplate": false,
      "tags": [],
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}
```

--------------------------------

### GET /api/carousels/:id/references

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Lists all reference images attached to a carousel.

```APIDOC
## GET /api/carousels/:id/references

### Description
Lists all reference images attached to a carousel that Claude can analyze for style matching.

### Method
GET

### Endpoint
/api/carousels/:id/references

### Parameters
#### Path Parameters
- **id** (string) - Required - The carousel ID

### Response
#### Success Response (200)
- **references** (array) - List of reference image objects
```

--------------------------------

### GET /api/carousels/:id/caption

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Retrieves the Instagram caption and hashtags for a carousel.

```APIDOC
## GET /api/carousels/:id/caption

### Description
Retrieves the Instagram caption and hashtags for a carousel.

### Method
GET

### Endpoint
/api/carousels/:id/caption

### Parameters
#### Path Parameters
- **id** (string) - Required - The carousel ID

### Response
#### Success Response (200)
- **caption** (string) - The carousel caption
- **hashtags** (array) - List of hashtags
```

--------------------------------

### GET /api/carousels/:id

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Retrieves complete data for a specific carousel, including all slides.

```APIDOC
## GET /api/carousels/:id

### Description
Retrieves complete carousel data including all slides with their HTML content.

### Method
GET

### Endpoint
/api/carousels/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the carousel

### Response
#### Success Response (200)
- **id** (string) - Carousel ID
- **slides** (array) - List of slide objects

#### Response Example
{
  "id": "xyz789",
  "name": "5 Morning Habits That Changed My Life",
  "slides": [
    {
      "id": "slide1",
      "html": "<div style=\"width: 1080px; height: 1350px; ...\">...</div>",
      "order": 0
    }
  ]
}
```

--------------------------------

### Get Carousel Caption

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Retrieves the Instagram caption and hashtags associated with a specific carousel. This is useful for reviewing or reusing existing caption content.

```bash
# Get caption and hashtags
curl -s http://localhost:3000/api/carousels/xyz789/caption
```

```json
# Response:
{
  "caption": "Stop waking up tired. These 5 morning habits changed everything for me.\n\nSave this for tomorrow morning ☀️",
  "hashtags": ["productivity", "morninghabits", "successmindset", "selfimprovement"]
}
```

--------------------------------

### Create a Carousel

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Initializes a new carousel project. Supported aspect ratios are 1:1, 4:5, and 9:16.

```bash
# Create a new carousel with portrait aspect ratio
curl -s -X POST http://localhost:3000/api/carousels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "5 Morning Habits That Changed My Life",
    "aspectRatio": "4:5"
  }'

# Response (201 Created):
{
  "id": "xyz789",
  "name": "5 Morning Habits That Changed My Life",
  "aspectRatio": "4:5",
  "slides": [],
  "referenceImages": [],
  "chatSessionId": null,
  "isTemplate": false,
  "tags": [],
  "createdAt": "2024-01-15T10:35:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}
```

--------------------------------

### Project Directory Structure

Source: https://github.com/hainrixz/open-carrusel/blob/main/README.md

Visual representation of the project file hierarchy.

```text
open-carrusel/
├── .claude/
│   └── commands/             ← /start, /stop, /reset, /doctor (Claude Code slash commands)
├── data/                     ← user state (gitignored): brand, carousels, templates, exports
├── docs/screenshots/         ← README assets
├── public/uploads/           ← user uploads (gitignored): logos, reference images
├── scripts/
│   ├── setup.mjs             ← npm install + seed data dirs + Claude CLI detection (cross-platform)
│   └── doctor.mjs            ← env diagnostic (zero deps, runs pre-install)
├── src/
│   ├── app/
│   │   ├── api/              ← every backend route (chat, carousels, slides, export, brand, ...)
│   │   ├── carousel/[id]/    ← editor page
│   │   ├── globals.css       ← Tailwind v4 theme + Emil-style motion tokens
│   │   ├── layout.tsx
│   │   └── page.tsx          ← dashboard page
│   ├── components/
│   │   ├── brand/            ← BrandSetup, ColorPicker, FontSelector, LogoUpload
│   │   ├── chat/             ← ChatPanel, ChatMessage, ChatInput, ReferenceImages
│   │   ├── editor/           ← CarouselPreview, SlideFilmstrip, SlideRenderer, ExportButton, ...
│   │   ├── layout/           ← TopBar
│   │   ├── templates/        ← TemplateGallery, TemplateCard
│   │   └── ui/               ← Button, Input, Badge, ConfirmDialog, CreateCarouselDialog
│   ├── lib/
│   │   ├── chat-system-prompt.ts   ← dynamic system prompt (brand + carousel context)
│   │   ├── slide-html.ts            ← wrapSlideHtml() — the rendering contract
│   │   ├── carousels.ts             ← carousel + slide CRUD with version history
│   │   ├── data.ts                  ← JSON storage with async-mutex + atomic writes
│   │   ├── claude-path.ts           ← portable Claude CLI discovery
│   │   └── ...
│   └── types/                ← shared TypeScript types
├── CLAUDE.md                 ← architecture doc for AI assistants working on this code
├── LICENSE                   ← MIT
├── README.md                 ← you are here
├── next.config.ts
├── package.json
└── tsconfig.json
```

--------------------------------

### POST /api/chat

Source: https://github.com/hainrixz/open-carrusel/blob/main/CLAUDE.md

Initiates a Claude CLI subprocess to handle AI-driven carousel generation using SSE streaming.

```APIDOC
## POST /api/chat

### Description
Spawns a Claude CLI subprocess to process chat requests and streams the response back via Server-Sent Events (SSE).

### Method
POST

### Endpoint
/api/chat
```

--------------------------------

### Upload Image or Font

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Uploads assets for use in slides. Images are processed via Sharp, while SVG files are rejected.

```bash
curl -s -X POST http://localhost:3000/api/upload \
  -F "file=@/path/to/image.png"
```

```bash
curl -s -X POST http://localhost:3000/api/upload \
  -F "file=@/path/to/custom-font.woff2"
```

--------------------------------

### Create Carousel from Template

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Creates a new carousel instance based on an existing template ID.

```bash
curl -s -X POST http://localhost:3000/api/templates/tmpl_001/use
```

--------------------------------

### Configure Claude CLI Path

Source: https://github.com/hainrixz/open-carrusel/blob/main/README.md

Environment variable configuration for specifying the Claude CLI path in .env.local.

```bash
CLAUDE_CLI_PATH=/path/to/claude   # set if `which claude` doesn't find it
```

--------------------------------

### POST /api/templates/:id/use

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Creates a new carousel from an existing template.

```APIDOC
## POST /api/templates/:id/use

### Description
Creates a new carousel with all slides copied from a specified template.

### Method
POST

### Endpoint
/api/templates/:id/use

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the template to use.
```

--------------------------------

### Save Carousel as Template

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Saves a carousel configuration as a reusable template.

```bash
curl -s -X POST http://localhost:3000/api/templates \
  -H "Content-Type: application/json" \
  -d '{
    "carouselId": "xyz789",
    "name": "Productivity Carousel Template",
    "description": "8-slide format with hook, value slides, and strong CTA"
  }'
```

--------------------------------

### List Available Fonts

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Retrieves a list of Google Fonts optimized for social media carousels.

```bash
curl -s http://localhost:3000/api/fonts
```

--------------------------------

### List Templates

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Returns a list of all saved carousel templates. Each template includes its ID, name, description, and aspect ratio.

```bash
# List all templates
curl -s http://localhost:3000/api/templates
```

```json
# Response:
{
  "templates": [
    {
      "id": "tmpl_001",
      "name": "Dark Mode Listicle",
      "description": "Bold hook + 5 content slides + CTA",
      "aspectRatio": "4:5",
      "slides": [...],
      "createdAt": "2024-01-10T08:00:00.000Z"
    }
  ]
}
```

--------------------------------

### List All Carousels

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Retrieves a list of all locally stored carousel projects, excluding templates.

```bash
# List all carousels
curl -s http://localhost:3000/api/carousels

# Response:
{
  "carousels": [
    {
      "id": "abc123",
      "name": "Morning Habits",
      "aspectRatio": "4:5",
      "slides": [],
      "referenceImages": [],
      "chatSessionId": null,
      "isTemplate": false,
      "tags": [],
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}
```

--------------------------------

### POST /api/carousels

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Creates a new carousel project with a specified name and aspect ratio.

```APIDOC
## POST /api/carousels

### Description
Creates a new carousel project with specified name and Instagram aspect ratio. Valid ratios are "1:1", "4:5", and "9:16".

### Method
POST

### Endpoint
/api/carousels

### Request Body
- **name** (string) - Required - The name of the carousel
- **aspectRatio** (string) - Required - The aspect ratio (1:1, 4:5, or 9:16)

### Request Example
{
  "name": "5 Morning Habits That Changed My Life",
  "aspectRatio": "4:5"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created carousel

#### Response Example
{
  "id": "xyz789",
  "name": "5 Morning Habits That Changed My Life",
  "aspectRatio": "4:5",
  "slides": [],
  "referenceImages": [],
  "chatSessionId": null,
  "isTemplate": false,
  "tags": [],
  "createdAt": "2024-01-15T10:35:00.000Z",
  "updatedAt": "2024-01-15T10:35:00.000Z"
}
```

--------------------------------

### POST /api/upload

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Uploads images or fonts for use in slides.

```APIDOC
## POST /api/upload

### Description
Uploads images (PNG, JPG, WebP) or fonts (WOFF2, TTF). Images are processed to be max 1080px, sRGB PNG, and EXIF stripped.

### Method
POST

### Endpoint
/api/upload

### Request Body
- **file** (file) - Required - The image or font file to upload.
```

--------------------------------

### Create a Hook Slide

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Adds a new slide to a carousel using a POST request with HTML content and optional notes.

```bash
curl -s -X POST http://localhost:3000/api/carousels/xyz789/slides \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"width: 1080px; height: 1350px; background: linear-gradient(135deg, #1a1a2e, #16213e); display: flex; flex-direction: column; justify-content: center; align-items: center; padding: 80px;\"><h1 style=\"font-family: \'\'Inter\'\', sans-serif; font-size: 72px; font-weight: 800; color: #ffffff; text-align: center; line-height: 1.2;\">Your morning routine is broken.</h1><p style=\"font-family: \'\'Inter\'\', sans-serif; font-size: 28px; color: #e94560; margin-top: 40px;\">swipe to fix it →</p></div>",
    "notes": "Hook slide - provocative statement"
  }'
```

--------------------------------

### POST /api/templates

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Saves a carousel as a template.

```APIDOC
## POST /api/templates

### Description
Saves a carousel as a template for future reuse.

### Method
POST

### Endpoint
/api/templates

### Request Body
- **carouselId** (string) - Required - The ID of the carousel to save.
- **name** (string) - Required - The name of the template.
- **description** (string) - Optional - A brief description of the template.

### Request Example
{
  "carouselId": "xyz789",
  "name": "Productivity Carousel Template",
  "description": "8-slide format with hook, value slides, and strong CTA"
}

### Response
#### Success Response (201)
- **id** (string) - The ID of the created template.
- **name** (string) - The name of the template.
- **description** (string) - The description of the template.
- **aspectRatio** (string) - The aspect ratio of the template.
- **slides** (array) - The slides contained in the template.
- **createdAt** (string) - ISO timestamp of creation.
```

--------------------------------

### Update Brand Configuration

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Updates the brand identity settings. Any slides generated after this update will reflect the new configuration. Ensure the Content-Type header is set to application/json.

```bash
# Update brand colors and fonts
curl -s -X PUT http://localhost:3000/api/brand \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Creator Studio",
    "colors": {
      "primary": "#000000",
      "secondary": "#1a1a1a",
      "accent": "#ff6b35",
      "background": "#ffffff",
      "surface": "#f8f8f8"
    },
    "fonts": {
      "heading": "Space Grotesk",
      "body": "DM Sans"
    },
    "styleKeywords": ["modern", "clean", "high contrast"]
  }'
```

```json
# Response:
{
  "name": "Creator Studio",
  "colors": { ... },
  "fonts": { "heading": "Space Grotesk", "body": "DM Sans" },
  "styleKeywords": ["modern", "clean", "high contrast"],
  "updatedAt": "2024-01-15T12:00:00.000Z"
}
```

--------------------------------

### Duplicate a Carousel

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Creates a copy of an existing carousel, resetting the chat session and version history.

```bash
# Duplicate carousel
curl -s -X POST http://localhost:3000/api/carousels/xyz789/duplicate

# Response (201 Created):
{
  "id": "copy_abc",
  "name": "10 Morning Habits for Success (copy)",
  "aspectRatio": "4:5",
  "slides": [...],
  "chatSessionId": null,
  "createdAt": "2024-01-15T11:10:00.000Z"
}
```

--------------------------------

### Reorder Slides

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Updates the sequence of slides by providing an array of slide IDs.

```bash
curl -s -X PUT http://localhost:3000/api/carousels/xyz789/slides \
  -H "Content-Type: application/json" \
  -d '{
    "slideIds": ["slide_003", "slide_001", "slide_002", "slide_004"]
  }'
```

--------------------------------

### Wrap Slide HTML

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Wraps body-level HTML into a full document structure for preview or export.

```typescript
import { wrapSlideHtml } from "@/lib/slide-html";
import type { AspectRatio } from "@/types/carousel";

// Slide HTML (body-level only, no document structure)
const slideHtml = `
<div style="
  width: 1080px;
  height: 1350px;
  background: linear-gradient(135deg, #1a1a2e, #16213e);
  display: flex;
  justify-content: center;
  align-items: center;
  padding: 80px;
">
  <h1 style="
    font-family: 'Playfair Display', serif;
    font-size: 72px;
    color: white;
    text-align: center;
  ">Your hook text here</h1>
</div>
`;

// Wrap for preview (loads fonts from Google CDN)
const previewHtml = wrapSlideHtml(slideHtml, "4:5");

// Wrap for export (inlined base64 font CSS)
const exportHtml = wrapSlideHtml(slideHtml, "4:5", {
  inlineFontCss: "@font-face { font-family: 'Playfair Display'; src: url(data:font/woff2;base64,...) }"
});
```

--------------------------------

### Export Carousel to PNG ZIP

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Exports all slides as a ZIP file containing PNG images. Uses Puppeteer for rendering.

```bash
curl -s -X POST http://localhost:3000/api/carousels/xyz789/export \
  --output carousel-export.zip
```

--------------------------------

### Delete Template

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Removes a specific template from the library.

```bash
curl -s -X DELETE http://localhost:3000/api/templates/tmpl_001
```

--------------------------------

### PUT /api/brand

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Updates brand identity settings.

```APIDOC
## PUT /api/brand

### Description
Updates brand identity settings. All slides generated after this will use the new brand configuration.

### Method
PUT

### Endpoint
/api/brand

### Request Body
- **name** (string) - Brand name
- **colors** (object) - Color palette
- **fonts** (object) - Font settings
- **styleKeywords** (array) - List of style keywords

### Request Example
{
  "name": "Creator Studio",
  "colors": {
    "primary": "#000000",
    "secondary": "#1a1a1a",
    "accent": "#ff6b35",
    "background": "#ffffff",
    "surface": "#f8f8f8"
  },
  "fonts": {
    "heading": "Space Grotesk",
    "body": "DM Sans"
  },
  "styleKeywords": ["modern", "clean", "high contrast"]
}
```

--------------------------------

### Add Reference Image

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Attaches a reference image to a carousel. The image is analyzed by Claude's Read tool to help replicate visual styles. The request requires a JSON body with the image URL and name.

```bash
# Add reference image
curl -s -X POST http://localhost:3000/api/carousels/xyz789/references \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/uploads/inspiration.png",
    "name": "Dark mode editorial style"
  }'
```

```json
# Response (201 Created):
{
  "id": "ref_002",
  "url": "/uploads/inspiration.png",
  "absPath": "/app/public/uploads/inspiration.png",
  "name": "Dark mode editorial style",
  "addedAt": "2024-01-15T11:00:00.000Z"
}
```

--------------------------------

### Export and Utility API

Source: https://github.com/hainrixz/open-carrusel/blob/main/CLAUDE.md

Endpoints for exporting carousels, managing brand settings, templates, image uploads, and font retrieval.

```APIDOC
## POST /api/carousels/[id]/export
### Description
Export all slides in a carousel to a PNG ZIP file.

## GET/PUT /api/brand
### Description
Retrieve or update brand configuration.

## GET/POST /api/templates
### Description
List or create carousel templates.

## POST /api/upload
### Description
Upload an image file (PNG, JPG, WebP). Max size 10MB.

## GET /api/fonts
### Description
Retrieve the list of available Google Fonts.
```

--------------------------------

### Update a Slide

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Updates existing slide HTML or notes. Previous versions are automatically saved for undo functionality.

```bash
curl -s -X PUT http://localhost:3000/api/carousels/xyz789/slides/slide_001 \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"width: 1080px; height: 1350px; background: #0f0f0f; display: flex; flex-direction: column; justify-content: center; align-items: center; padding: 100px;\"><h1 style=\"font-family: \'\'Playfair Display\'\', serif; font-size: 84px; font-weight: 700; color: #ffffff; text-align: center;\">Stop waking up tired.</h1></div>",
    "notes": "Hook slide - question format"
  }'
```

--------------------------------

### POST /api/carousels/:id/duplicate

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Creates a copy of an existing carousel.

```APIDOC
## POST /api/carousels/:id/duplicate

### Description
Creates a complete copy of an existing carousel with all slides, resetting chat session and version history.

### Method
POST

### Endpoint
/api/carousels/:id/duplicate

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the carousel to duplicate

### Response
#### Success Response (201)
- **id** (string) - The ID of the new duplicated carousel
```

--------------------------------

### Send Message to Claude

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Interacts with the AI chat API to generate or modify slides. Supports initial creation and session-based updates.

```bash
curl -N -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a 5-slide carousel about productivity hacks for remote workers. Dark mode, bold typography, accent red.",
    "carouselId": "xyz789"
  }'
```

```bash
curl -N -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Make slide 3 more minimal - remove the background pattern",
    "sessionId": "session_abc123",
    "carouselId": "xyz789"
  }'
```

--------------------------------

### POST /api/carousels/:id/references

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Attaches a reference image to a carousel.

```APIDOC
## POST /api/carousels/:id/references

### Description
Attaches a reference image to a carousel. Claude will use the Read tool to analyze these images and replicate their visual style.

### Method
POST

### Endpoint
/api/carousels/:id/references

### Parameters
#### Path Parameters
- **id** (string) - Required - The carousel ID

### Request Body
- **url** (string) - Required - Image URL
- **name** (string) - Required - Image name
```

--------------------------------

### Chat API for AI Slide Generation

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Endpoint for interacting with an AI model to generate or modify carousel slides.

```APIDOC
## POST /api/chat

### Description
Sends a message to an AI model (Claude CLI) to generate or modify carousel slides. Returns a Server-Sent Events (SSE) stream with progress and results.

### Method
POST

### Endpoint
/api/chat

### Parameters
#### Request Body
- **message** (string) - Required - The user's prompt or instruction for the AI.
- **carouselId** (string) - Required - The ID of the carousel context for the AI.
- **sessionId** (string) - Optional - The ID of an existing chat session to resume.

### Request Example (Start New Chat)
```bash
curl -N -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{ 
    "message": "Create a 5-slide carousel about productivity hacks for remote workers. Dark mode, bold typography, accent red.",
    "carouselId": "xyz789"
  }'
```

### Request Example (Resume Chat)
```bash
curl -N -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{ 
    "message": "Make slide 3 more minimal - remove the background pattern",
    "sessionId": "session_abc123",
    "carouselId": "xyz789"
  }'
```

### Response
#### Success Response (200 OK)
- Returns a Server-Sent Events (SSE) stream. Each event is a JSON object:
  - `data: {"type":"token","text":"..."}`: Partial text generated by the AI.
  - `data: {"type":"result","text":"..."}`: Final result or summary of the AI's action.
  - `event: done` followed by `data: {"sessionId":"...","exitCode":...}`: Indicates the end of the session.

#### SSE Response Example Stream:
```
data: {"type":"token","text":"I'll create"}
data: {"type":"token","text":" a compelling"}
data: {"type":"token","text":" carousel..."}
data: {"type":"result","text":"Created 5 slides with dark mode theme..."}
event: done
data: {"sessionId":"session_abc123","exitCode":0}
```
```

--------------------------------

### Carousel Management API

Source: https://github.com/hainrixz/open-carrusel/blob/main/CLAUDE.md

Endpoints for listing, creating, retrieving, updating, and deleting carousels.

```APIDOC
## GET/POST /api/carousels

### Description
List all carousels or create a new one.

## GET/PUT/DELETE /api/carousels/[id]

### Description
Retrieve, update, or delete a specific carousel by its ID.

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the carousel.
```

--------------------------------

### Slide Management API

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Endpoints for managing individual slides within a carousel, including creation, updates, deletion, and undo functionality.

```APIDOC
## POST /api/carousels/{carouselId}/slides

### Description
Creates a new slide within a specified carousel.

### Method
POST

### Endpoint
/api/carousels/{carouselId}/slides

### Parameters
#### Path Parameters
- **carouselId** (string) - Required - The ID of the carousel to add the slide to.

#### Request Body
- **html** (string) - Required - The HTML content of the slide.
- **notes** (string) - Optional - Internal notes about the slide.

### Request Example
```json
{
  "html": "<div style=\"width: 1080px; height: 1350px; background: linear-gradient(135deg, #1a1a2e, #16213e); display: flex; flex-direction: column; justify-content: center; align-items: center; padding: 80px;"><h1 style=\"font-family: '\''Inter'\'', sans-serif; font-size: 72px; font-weight: 800; color: #ffffff; text-align: center; line-height: 1.2;\">Your morning routine is broken.</h1><p style=\"font-family: '\''Inter'\'', sans-serif; font-size: 28px; color: #e94560; margin-top: 40px;\">swipe to fix it →</p></div>",
  "notes": "Hook slide - provocative statement"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the newly created slide.
- **html** (string) - The HTML content of the slide.
- **previousVersions** (array) - An array of previous HTML versions of the slide.
- **order** (integer) - The display order of the slide.
- **notes** (string) - Internal notes about the slide.

#### Response Example
```json
{
  "id": "slide_001",
  "html": "<div style=\"width: 1080px; height: 1350px; ...">...</div>",
  "previousVersions": [],
  "order": 0,
  "notes": "Hook slide - provocative statement"
}
```

## PUT /api/carousels/{carouselId}/slides/{slideId}

### Description
Updates the HTML content or notes of an existing slide. Previous versions are automatically saved.

### Method
PUT

### Endpoint
/api/carousels/{carouselId}/slides/{slideId}

### Parameters
#### Path Parameters
- **carouselId** (string) - Required - The ID of the carousel containing the slide.
- **slideId** (string) - Required - The ID of the slide to update.

#### Request Body
- **html** (string) - Optional - The new HTML content for the slide.
- **notes** (string) - Optional - The new internal notes for the slide.

### Request Example
```json
{
  "html": "<div style=\"width: 1080px; height: 1350px; background: #0f0f0f; display: flex; flex-direction: column; justify-content: center; align-items: center; padding: 100px;"><h1 style=\"font-family: '\''Playfair Display'\'', serif; font-size: 84px; font-weight: 700; color: #ffffff; text-align: center;\">Stop waking up tired.</h1></div>",
  "notes": "Hook slide - question format"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The ID of the updated slide.
- **html** (string) - The updated HTML content.
- **previousVersions** (array) - An array of previous HTML versions.
- **order** (integer) - The display order of the slide.
- **notes** (string) - The updated internal notes.

#### Response Example
```json
{
  "id": "slide_001",
  "html": "<div style=\"width: 1080px; ...">...</div>",
  "previousVersions": ["<div style=\"width: 1080px; height: 1350px; background: linear-gradient..."],
  "order": 0,
  "notes": "Hook slide - question format"
}
```

## DELETE /api/carousels/{carouselId}/slides/{slideId}

### Description
Removes a slide from a carousel and reorders the remaining slides.

### Method
DELETE

### Endpoint
/api/carousels/{carouselId}/slides/{slideId}

### Parameters
#### Path Parameters
- **carouselId** (string) - Required - The ID of the carousel containing the slide.
- **slideId** (string) - Required - The ID of the slide to delete.

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the deletion was successful.

#### Response Example
```json
{ "success": true }
```

## PUT /api/carousels/{carouselId}/slides

### Description
Reorders the slides within a carousel by providing a new sequence of slide IDs.

### Method
PUT

### Endpoint
/api/carousels/{carouselId}/slides

### Parameters
#### Path Parameters
- **carouselId** (string) - Required - The ID of the carousel whose slides are being reordered.

#### Request Body
- **slideIds** (array of strings) - Required - An array of slide IDs in the desired order.

### Request Example
```json
{
  "slideIds": ["slide_003", "slide_001", "slide_002", "slide_004"]
}
```

### Response
#### Success Response (200 OK)
- **slides** (array) - An array of slide objects, each with an updated `order` field.

#### Response Example
```json
{
  "slides": [
    { "id": "slide_003", "order": 0, ... },
    { "id": "slide_001", "order": 1, ... },
    { "id": "slide_002", "order": 2, ... },
    { "id": "slide_004", "order": 3, ... }
  ]
}
```

## POST /api/carousels/{carouselId}/slides/{slideId}/undo

### Description
Reverts a slide to its previous version from its history.

### Method
POST

### Endpoint
/api/carousels/{carouselId}/slides/{slideId}/undo

### Parameters
#### Path Parameters
- **carouselId** (string) - Required - The ID of the carousel containing the slide.
- **slideId** (string) - Required - The ID of the slide to revert.

### Response
#### Success Response (200 OK)
- **id** (string) - The ID of the reverted slide.
- **html** (string) - The HTML content of the reverted slide.
- **previousVersions** (array) - An array of remaining previous HTML versions.
- **order** (integer) - The display order of the slide.
- **notes** (string) - The internal notes of the slide.

#### Response Example
```json
{
  "id": "slide_001",
  "html": "<div style=\"width: 1080px; height: 1350px; background: linear-gradient..."",
  "previousVersions": [],
  "order": 0,
  "notes": "Hook slide"
}
```

#### Error Response (404 Not Found)
- **error** (string) - Message indicating no history or slide not found.

#### Error Response Example
```json
{ "error": "Not found or no previous versions" }
```
```

--------------------------------

### Slide Management API

Source: https://github.com/hainrixz/open-carrusel/blob/main/CLAUDE.md

Endpoints for managing individual slides within a carousel, including adding, updating, deleting, reordering, and undoing changes.

```APIDOC
## POST /api/carousels/[id]/slides
### Description
Add a new slide to a carousel.

## PUT/DELETE /api/carousels/[id]/slides/[slideId]
### Description
Update or delete a specific slide.

## PUT /api/carousels/[id]/slides
### Description
Reorder slides within a carousel.
### Request Body
- **slideIds** (array) - Required - An ordered list of slide IDs.

## POST /api/carousels/[id]/slides/[slideId]/undo
### Description
Undo the last change made to a specific slide.
```

--------------------------------

### Undo Slide Changes

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Reverts a slide to its previous HTML version using the version history.

```bash
curl -s -X POST http://localhost:3000/api/carousels/xyz789/slides/slide_001/undo
```

--------------------------------

### Access Instagram Carousel Dimensions

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Defines standard aspect ratios and carousel limits for Instagram content generation.

```typescript
import { DIMENSIONS, MAX_SLIDES, MAX_VERSIONS } from "@/types/carousel";
import type { AspectRatio } from "@/types/carousel";

// Available aspect ratios and their pixel dimensions
const dimensions = {
  "1:1": { width: 1080, height: 1080 },   // Square
  "4:5": { width: 1080, height: 1350 },   // Portrait (recommended)
  "9:16": { width: 1080, height: 1920 }   // Story/Reel
};

// Usage
const ratio: AspectRatio = "4:5";
const { width, height } = DIMENSIONS[ratio];
// width: 1080, height: 1350

// Limits
const maxSlidesPerCarousel = MAX_SLIDES;  // 20
const maxVersionHistory = MAX_VERSIONS;    // 5
```

--------------------------------

### Update a Carousel

Source: https://context7.com/hainrixz/open-carrusel/llms.txt

Modifies metadata for an existing carousel, such as its name or tags.

```bash
# Update carousel name and tags
curl -s -X PUT http://localhost:3000/api/carousels/xyz789 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "10 Morning Habits for Success",
    "tags": ["productivity", "lifestyle"]
  }'

# Response:
{
  "id": "xyz789",
  "name": "10 Morning Habits for Success",
  "aspectRatio": "4:5",
  "tags": ["productivity", "lifestyle"],
  "updatedAt": "2024-01-15T11:05:00.000Z"
}
```