---
title: "Create a binder, optionally with its first items"
method: POST
path: "/binders"
---

# Create a binder, optionally with its first items

`POST /binders`

## Request

- Base URL: `https://lucid.page`
- URL: `https://lucid.page/binders`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `apiKey`
  - none

Items keep the order given. Limits: 100 binders per account, 500 items per binder.

## Request body

- CreateBinderRequest
  - `title` string, required
  - `description` string
  - `visibility` 'private' | 'unlisted' | 'public'
  - `items` ItemInput[]
    - `slug` string: A lucid.page page: yours, or any public or unlisted page. Send slug or url, not both.
    - `url` string: An http or https link. A lucid.page page URL (/{slug}, /{slug}.md or /raw/{slug}) is stored as a page item.
    - `title` string: Link items only (ignored for pages); defaults to the link's hostname
    - `note` string

## Response `201`

Created

- Binder
  - `slug` string, required: Derived from the title at creation; never changes
  - `title` string, required
  - `description` string, required
  - `visibility` 'private' | 'unlisted' | 'public', required
  - `url` string, required: The binder page, https://lucid.page/b/{slug}. It 404s while the binder is private.
  - `item_count` integer, required
  - `version` integer, required: Bumped by every change; send it back as expected_version
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `items` BinderItem[], required: In display order
    - `id` string, required
    - `kind` 'page' | 'link', required
    - `slug` string, nullable, required: The page's slug; null for links
    - `url` string, required: The page's absolute URL, or the link
    - `title` string, required: The page's current title, or the link's title (its hostname if none was set)
    - `note` string, required
    - `public_visible` boolean, required: Whether the item shows on the binder page. Links always do. A page does while it exists, is not blocked or expired, and is public, or unlisted in an unlisted or private binder.
    - `added_at` string, date-time, required

## Other responses

- `400`: Invalid title, description, visibility, or item
- `401`: Authentication required
- `404`: An item's page does not exist or is not readable
- `409`: Binder or item limit reached, or a duplicate item
- `413`: Request body over 4 MiB

---

[API](https://skmtc.dev/lucid/apis/lucid-page.md) · [All operations](https://skmtc.dev/lucid/apis/lucid-page/llms.txt) · [OpenAPI document](https://skmtc.dev/lucid/apis/lucid-page/revisions/ac6b8c27c38b?raw)