# Flipbook

> Flipbook turns any document (PDF, slides, images) into a beautiful, embeddable flipbook with realistic 3D page-turn. Built for humans — and for AI agents.

Docs entrypoint: https://flipbook.it.com/agents
OpenAPI spec:    https://flipbook.it.com/openapi.yaml
Plugin manifest: https://flipbook.it.com/.well-known/ai-plugin.json

## Try it now (no key required)

```
curl https://urmuupgjgyacsuvmqyhc.supabase.co/functions/v1/api-v1/flipbooks
```

Flipbook exposes a pay-as-you-go REST API and an MCP (Model Context Protocol) server so autonomous agents and LLMs can create, publish, share, and embed flipbooks with no human in the loop.

## REST API

- Base URL: `https://urmuupgjgyacsuvmqyhc.supabase.co/functions/v1/api-v1`
- Auth: **Reads are open** — `GET` endpoints for public flipbooks work with no key. Writes and access to private flipbooks need `Authorization: Bearer fk_live_...` — create keys at https://flipbook.it.com/dashboard
- Pricing: $1.00 USD per flipbook created via API. No monthly minimum, no per-seat fees.
- OpenAPI 3.1 spec: https://flipbook.it.com/openapi.yaml
- Full docs: https://flipbook.it.com/agents

### Core endpoints

- `POST /flipbooks` — Create a flipbook from `pages[]` (array of page image URLs). Returns `{ id, slug, url, embed_url, page_count }`.
- `GET  /flipbooks` — With no key: lists all public flipbooks. With a key: lists flipbooks owned by the API key's user (includes private).
- `GET  /flipbooks/{id_or_slug}` — Fetch a flipbook. Public flipbooks readable without a key; private flipbooks require the owner's key. Anonymous responses omit raw `page_urls` (use `embed_url`).
- `PATCH /flipbooks/{id}` — Update title, description, slug, or visibility.
- `DELETE /flipbooks/{id}` — Delete a flipbook.
- `GET  /flipbooks/{id}/embed` — Get an iframe embed URL and HTML snippet.

### Conventions

- All requests and responses are JSON.
- Idempotency: pass `Idempotency-Key: <uuid>` on POST to safely retry.
- Errors follow `{ "error": { "code": "...", "message": "...", "param": "..." } }`.
- Rate limit: 60 requests/minute per key, or per IP for anonymous callers (burst 120). Returns `429` with `Retry-After`.

## MCP server

- Endpoint: `https://urmuupgjgyacsuvmqyhc.supabase.co/functions/v1/mcp`
- Transport: Streamable HTTP (MCP spec 2025-06-18+)
- Auth: OAuth 2.1 with dynamic client registration. Sign in as a Flipbook user during consent; no manual token paste.
- Discovery: `https://urmuupgjgyacsuvmqyhc.supabase.co/functions/v1/mcp/.well-known/oauth-protected-resource`
- Tools: `create_flipbook`, `list_flipbooks`, `get_flipbook`, `update_flipbook`, `delete_flipbook`, `get_embed_code`.

### Add to Claude Desktop, Cursor, or ChatGPT

Claude Desktop (`claude_desktop_config.json`) / Cursor (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "flipbook": {
      "url": "https://urmuupgjgyacsuvmqyhc.supabase.co/functions/v1/mcp"
    }
  }
}
```

The client will open the Flipbook consent screen the first time it connects.

## Pages worth knowing

- [Agents & LLM docs](/agents): Getting-started guide and code examples.
- [Pricing](/#pricing): Plans and the $1/flipbook Agents tier.
- [Home](/): Product overview and live demo.
- [OpenAPI spec](/openapi.yaml): Machine-readable API contract.