# Banatie Documentation — Full Specification for Claude Code

**Date:** December 30, 2025  
**Purpose:** Complete specification for generating documentation pages  
**Source of Truth:** `/docs/api/*.md` in banatie-service repository  
**Target:** `/apps/landing/src/app/docs/`

---

## Documentation Spirit & Voice

**This is critical. Every page must follow this approach:**

### Tone
- **Technical but approachable** — developers respect precision, but don't want to read a manual
- **Confident, not arrogant** — we know our product works, no need to oversell
- **Direct** — say what you mean, no fluff, no filler phrases
- **Second person** — "you", "your", not "the user" or "one"

### Content Philosophy
- **"Easy and simple" is the vibe** — everything should feel lightweight
- **Positive statements over negatives** — say what we DO, not what we don't
- **Show, don't tell** — code examples over explanations
- **One request, one result** — emphasize simplicity of the flow
- **Production-ready** — everything we deliver is ready to ship, not a prototype

### What to Avoid
- Filler phrases ("In this section we will discuss...")
- Marketing speak ("revolutionary", "game-changing", "cutting-edge")
- Unnecessary warnings and caveats
- Over-explaining simple concepts
- Walls of text without visual breaks

### Visual Variety
Use callouts, tables, code blocks liberally. Break up text. Make pages scannable.

---

## URL Structure (Final, SEO-Critical)

```
/docs                    # Getting Started
/docs/generation         # Image Generation (main guide)
/docs/images             # Working with Images
/docs/live-urls          # Live URL Generation
/docs/authentication     # API Keys & Auth (after live-urls)
/docs/api                # API Reference Overview
/docs/api/generations    # Generations endpoints
/docs/api/images         # Images endpoints
/docs/api/flows          # Flows endpoints
/docs/api/live-scopes    # Live Scopes endpoints
```

**10 pages total.** URLs are permanent — do not change after deployment.

---

## Sidebar Navigation

Two-level navigation:

```
Getting Started          → /docs
Image Generation         → /docs/generation
Working with Images      → /docs/images
Live URLs                → /docs/live-urls
Authentication           → /docs/authentication
API Reference            → /docs/api (expandable group)
  ├─ Overview            → /docs/api
  ├─ Generations         → /docs/api/generations
  ├─ Images              → /docs/api/images
  ├─ Flows               → /docs/api/flows
  └─ Live Scopes         → /docs/api/live-scopes
```

"API Reference" section is collapsible/expandable in sidebar.

---

## Design System

Use existing components from the landing app. Key elements:

- **Code blocks** with syntax highlighting and copy button
- **Tables** for parameters, status codes, response fields
- **Callout blocks:**
  - 💡 **Tip** — helpful hints, pro tips
  - ⚠️ **Warning** — important cautions
  - 📝 **Note** — additional context
  - 🔒 **Security** — auth/security related
- **Response blocks** with status badges
- **Card links** for navigation to related pages
- **Breadcrumbs** for orientation

**Visual variety is important** — break up walls of text with callouts, tables, code examples.

---

## Cross-Linking Strategy

Every guide page should link to corresponding API Reference section.  
Every API Reference page should link back to the guide for context.

Examples:
- `/docs/generation` → "See full endpoint details in [API Reference: Generations](/docs/api/generations)"
- `/docs/api/generations` → "For concepts and examples, see [Image Generation guide](/docs/generation)"

---

## Page Specifications

---

### Page 1: `/docs` — Getting Started

**SEO Title:** "Getting Started with Banatie API | AI Image Generation"  
**Meta Description:** "Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN."

**Purpose:** First-time visitor lands here. Show them the value immediately.

**CONTENT — USE EXACTLY AS WRITTEN:**

```markdown
# Get Started

Generate your first AI image in a few simple steps.

## What is Banatie?

Banatie is an image generation API for developers. Send a text prompt, get a production-ready image delivered via CDN. 

Simple REST API. Optimized AI models that deliver consistent results. Images ready for production use immediately.

## Your First Image

Once you have your API key, generate an image with a single request:

```bash
curl -X POST https://api.banatie.app/api/v1/generations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"prompt": "a friendly robot waving hello"}'
```

That's it. The response contains your image:

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "outputImage": {
      "storageUrl": "https://cdn.banatie.app/my-org/my-project/img/8a3b2c1d-4e5f-6789-abcd-ef0123456789",
      "width": 1792,
      "height": 1008
    }
  }
}
```

Open `storageUrl` in your browser — there's your robot.

## Production Ready

The image URL is permanent and served via global CDN. What this means for you:

- **Fast access** — images load in milliseconds
- **Edge cached** — served from locations closest to your users
- **Global distribution** — works fast everywhere in the world

One request. Production-ready result. Drop the URL into your app and ship.

## Live URLs

Want to skip the API call entirely? 

Generate images directly from a URL:

```
https://cdn.banatie.app/my-org/my-project/live/demo?prompt=a+friendly+robot+waving+hello
```

Put this in an `<img src="...">` tag. First request generates the image, all subsequent requests serve it from cache instantly.

Perfect for placeholders, dynamic content, and rapid prototyping.

→ **[Learn more about Live URLs](/docs/live-urls)**

## Get Your API Key

We're currently in early access. API keys are issued personally.

**To request access:**
1. Go to [banatie.app](https://banatie.app)
2. Enter your email in the signup form
3. We'll send your API key within 24 hours

## Next Steps

- **[Image Generation](/docs/generation)** — Aspect ratios, prompt templates, using references
- **[Working with Images](/docs/images)** — Upload your own, organize with aliases
- **[Live URLs](/docs/live-urls)** — Generate images directly from URL parameters
- **[API Reference](/docs/api)** — Full endpoint documentation
```

---

### Page 2: `/docs/generation` — Image Generation

**SEO Title:** "Image Generation | Banatie API Docs"  
**Meta Description:** "Generate AI images from text prompts. Supports references, prompt templates, and chaining."

**Sections:**

1. **Basic Generation**
   - POST /api/v1/generations
   - Simple example: just prompt
   - Response with status, outputImage, storageUrl
   - Emphasize: one request → image ready
   
2. **Aspect Ratios**
   - Table of supported ratios with use cases
   - 1:1, 16:9, 9:16, 3:2, 21:9
   
3. **Prompt Templates**
   - Templates improve your prompt for specific styles
   - Available templates: general, photorealistic, illustration, minimalist, sticker, product, comic
   - Example showing how template affects the result
   - **Note callout:** Template selection coming soon. Currently uses general style.
   
4. **Using Reference Images**
   - Add referenceImages array with image IDs
   - Example with UUID reference
   - **Pro Tip callout:** You can also use aliases like `@logo` instead of UUIDs. See [Working with Images](/docs/images) to learn about aliases.
   - Auto-detection from prompt text (if you mention @alias in prompt)
   
5. **Continuing Generation**
   - Pass the same flowId to chain generations
   - Each response includes flowId for continuation
   - Keep it brief, not a major feature highlight
   
6. **Regeneration**
   - POST /api/v1/generations/:id/regenerate
   - Same params, new image, same URL

**Link to:** `/docs/api/generations` for full endpoint reference

---

### Page 3: `/docs/images` — Working with Images

**SEO Title:** "Working with Images | Banatie API Docs"  
**Meta Description:** "Upload, manage, and organize your images. CDN delivery, aliases, and image management."

**Sections:**

1. **Image URLs**
   - All images served via CDN: `https://cdn.banatie.app/...`
   - Format: `/{org}/{project}/img/{imageId}`
   - Fast, cached, globally distributed
   
2. **Uploading Images**
   - POST /api/v1/images/upload
   - Multipart form data
   - Use cases: brand assets, reference images, logos
   
3. **Listing & Getting Images**
   - GET /api/v1/images
   - GET /api/v1/images/:id
   
4. **Aliases**
   - Assign memorable names to images
   - Format: @alias-name (e.g., @logo, @hero-bg)
   - PUT /api/v1/images/:id with alias field
   - Access via CDN: `/{org}/{project}/img/@hero`
   
   **Pro Tip callout:** Use aliases for brand assets like `@logo`, `@brand-colors`. Reference them in generations without remembering UUIDs.

5. **Deleting Images**
   - DELETE /api/v1/images/:id

**Link to:** `/docs/api/images` for full endpoint reference

---

### Page 4: `/docs/live-urls` — Live URL Generation

**SEO Title:** "Live URLs | Banatie API Docs"  
**Meta Description:** "Generate images directly from URL parameters. No API calls needed — just use the URL in your HTML."

**This is a highlight feature page — make it compelling but not salesy.**

**Sections:**

1. **The Concept**
   - Generate images by putting prompt in URL
   - Use directly in `<img src="...">`
   - First request generates, subsequent requests serve from cache
   
2. **URL Format**
   ```
   https://cdn.banatie.app/{org}/{project}/live/{scope}?prompt=...&aspectRatio=...
   ```
   
3. **Try It**
   - Show a complete URL example they can open in browser
   
4. **Caching Behavior**
   - Cache HIT: instant, from CDN edge
   - Cache MISS: generates new image (few seconds)
   - X-Cache-Status header tells you which
   
5. **Scopes**
   - Organize live generations by scope
   - Set limits per scope
   - Auto-created on first use (if enabled)
   
6. **Rate Limits**
   - 10 new generations per hour per IP
   - Cache hits are unlimited
   
7. **Use Cases**
   - Dynamic placeholders during development
   - Personalized content
   - Rapid prototyping
   - HTML emails with dynamic images

**Link to:** `/docs/api/live-scopes` for scope management endpoints

---

### Page 5: `/docs/authentication` — Authentication

**SEO Title:** "Authentication | Banatie API Docs"  
**Meta Description:** "How to authenticate with Banatie API using API keys."

**Sections:**

1. **Early Access**
   - Currently in early access phase
   - API keys are issued personally via email
   - To request access: sign up on [banatie.app](https://banatie.app)
   
2. **Using Your API Key**
   - All API requests require `X-API-Key` header
   - Example: `curl -H "X-API-Key: your_key_here" ...`
   - Keep your key secret, don't commit to git
   
3. **Key Types** (brief)
   - Project Key: for your application
   - Master Key: for admin operations (you probably don't need this)

**Note callout:** API key management dashboard coming soon. For now, contact us if you need to rotate your key.

**Link to:** `/docs/generation` as next step

---

### Page 6: `/docs/api` — API Reference Overview

**SEO Title:** "API Reference | Banatie API Docs"  
**Meta Description:** "Complete REST API reference for Banatie. All endpoints, parameters, and response formats."

**This is a hub page — brief intro then links to subsections.**

**Sections:**

1. **Base URL**
   ```
   https://api.banatie.app
   ```
   
2. **Authentication**
   - All endpoints require `X-API-Key` header
   - Link to `/docs/authentication`
   
3. **Response Format**
   - Success: `{ "success": true, "data": {...} }`
   - Error: `{ "success": false, "error": {...} }`
   - Pagination pattern
   
4. **Common Error Codes**
   - Table of HTTP status codes and meanings
   
5. **Rate Limits**
   - 100 requests per hour
   - Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
   
6. **Endpoints**
   - Card links to each subsection:
     - Generations — create and manage image generations
     - Images — upload and organize images
     - Flows — manage generation chains
     - Live Scopes — control live URL generation

---

### Page 7: `/docs/api/generations` — Generations Endpoints

**SEO Title:** "Generations API | Banatie API Reference"

**Style:** Dry, complete, scannable. This is reference material.

**Endpoints to document:**

```
POST   /api/v1/generations                    Create generation
GET    /api/v1/generations                    List generations
GET    /api/v1/generations/:id                Get generation
DELETE /api/v1/generations/:id                Delete generation
POST   /api/v1/generations/:id/regenerate     Regenerate
PUT    /api/v1/generations/:id                Update generation
```

**For each endpoint:**
- Method + Path
- Description (1 line)
- Request parameters (table)
- Request body example (where applicable)
- Response example
- Notes if applicable

**Source:** Use `/docs/api/image-generation.md` and `/docs/api/image-generation-advanced.md`

**Important:** The API is synchronous. POST returns completed generation with outputImage immediately. Do NOT show polling flow.

**Link to:** `/docs/generation` for guide/context

---

### Page 8: `/docs/api/images` — Images Endpoints

**SEO Title:** "Images API | Banatie API Reference"

**Endpoints:**

```
POST   /api/v1/images/upload     Upload image
GET    /api/v1/images            List images
GET    /api/v1/images/:id        Get image (supports @alias)
PUT    /api/v1/images/:id        Update image (set alias, metadata)
DELETE /api/v1/images/:id        Delete image
```

**CDN Endpoints (public, no auth):**

```
GET    /cdn/{org}/{project}/img/{id}       Get image by UUID
GET    /cdn/{org}/{project}/img/@{alias}   Get image by alias
```

**Source:** Use `/docs/api/images-upload.md`

**Link to:** `/docs/images` for guide/context

---

### Page 9: `/docs/api/flows` — Flows Endpoints

**SEO Title:** "Flows API | Banatie API Reference"

**Brief intro:** Flows group related generations together. They're created automatically when you chain generations using the same flowId.

**Endpoints:**

```
GET    /api/v1/flows                         List flows
GET    /api/v1/flows/:id                     Get flow
GET    /api/v1/flows/:id/generations         List flow generations
GET    /api/v1/flows/:id/images              List flow images
PUT    /api/v1/flows/:id/aliases             Update flow aliases
DELETE /api/v1/flows/:id/aliases/:alias      Remove flow alias
DELETE /api/v1/flows/:id                     Delete flow
POST   /api/v1/flows/:id/regenerate          Regenerate last in flow
```

**Source:** Use `/docs/api/image-generation-advanced.md` section on flows

**Link to:** `/docs/generation` (section on continuing generations)

---

### Page 10: `/docs/api/live-scopes` — Live Scopes Endpoints

**SEO Title:** "Live Scopes API | Banatie API Reference"

**Endpoints:**

```
POST   /api/v1/live/scopes                   Create scope
GET    /api/v1/live/scopes                   List scopes
GET    /api/v1/live/scopes/:slug             Get scope
PUT    /api/v1/live/scopes/:slug             Update scope
DELETE /api/v1/live/scopes/:slug             Delete scope
POST   /api/v1/live/scopes/:slug/regenerate  Regenerate scope images
```

**CDN Live Endpoint (public):**

```
GET    /cdn/{org}/{project}/live/{scope}?prompt=...   Live generation
```

Query parameters: prompt (required), aspectRatio, autoEnhance, template

**Source:** Use `/docs/api/live-url.md`

**Link to:** `/docs/live-urls` for guide/context

---

## Implementation Notes for Claude Code

1. **Use existing components** — Check `/apps/landing/src/app/docs/` for current implementation patterns

2. **Correct URLs everywhere:**
   - API: `https://api.banatie.app`
   - CDN: `https://cdn.banatie.app`
   - NOT `.com` — always `.app`

3. **Example paths use:** `my-org/my-project` (not `default/my-project`)

4. **No SDK references** — We don't have SDK yet. Don't mention it.

5. **API is synchronous** — POST /generations returns completed result immediately. No polling.

6. **Prompt templates, not "enhancement"** — We have templates that improve prompts. Don't call it "auto-enhance" as a standalone feature.

7. **Breadcrumbs:** Every page should show path (e.g., "Docs > API Reference > Generations")

8. **Meta tags:** Each page needs proper SEO title and description as specified

9. **Mobile responsive** — Documentation must work well on mobile

10. **Code examples:** Use `bash` (curl) as primary. Show request AND response for every endpoint.

11. **Image dimensions in examples:** Use 1792 x 1008 (16:9) not 1024 x 1024

---

## File Structure Expected

```
apps/landing/src/app/docs/
├── page.tsx                    # /docs (Get Started)
├── generation/
│   └── page.tsx               # /docs/generation
├── images/
│   └── page.tsx               # /docs/images
├── live-urls/
│   └── page.tsx               # /docs/live-urls
├── authentication/
│   └── page.tsx               # /docs/authentication
└── api/
    ├── page.tsx               # /docs/api (Overview)
    ├── generations/
    │   └── page.tsx           # /docs/api/generations
    ├── images/
    │   └── page.tsx           # /docs/api/images
    ├── flows/
    │   └── page.tsx           # /docs/api/flows
    └── live-scopes/
        └── page.tsx           # /docs/api/live-scopes
```

---

## Priority Order for Implementation

1. `/docs` — Get Started (content provided above)
2. `/docs/generation` — Core feature
3. `/docs/api` — Reference hub
4. `/docs/api/generations` — Most used endpoints
5. `/docs/images` — Working with results
6. `/docs/api/images` — Image endpoints
7. `/docs/live-urls` — Highlight feature
8. `/docs/api/live-scopes` — Live management
9. `/docs/authentication` — Auth info
10. `/docs/api/flows` — Least priority (advanced users)

---

## Quality Checklist

Before marking complete, verify:

- [ ] All URLs use `banatie.app` (not `.com`)
- [ ] Example paths use `my-org/my-project`
- [ ] Image dimensions are 1792 x 1008 in examples
- [ ] All code examples are copy-paste ready
- [ ] Every endpoint shows request AND response
- [ ] Tables render correctly
- [ ] Callout blocks used for visual variety
- [ ] Cross-links between guide and reference pages
- [ ] Sidebar navigation matches URL structure
- [ ] Breadcrumbs work on all pages
- [ ] Mobile rendering is acceptable
- [ ] No references to SDK or features that don't exist
- [ ] No polling/async flow — API is synchronous
- [ ] SEO titles and descriptions set for all pages
- [ ] Tone matches "Documentation Spirit" section

---

**End of Specification**
