listicle

Bootstrap

Everything an operator (Claude, CLI, or curl) needs to start hitting the API: the env it’s talking to, how to authenticate, the full endpoint catalog, and a sample of available lists.

Environment
production
Base URL
https://www.listicle.xyz
Auth
anonymous

Your API key

Sign in to view or generate your key.

How to authenticate

Two ways to authenticate:

**API key (preferred for Claude / CLI):** include the key in every request.

```
curl -s -H 'X-API-Key: <your-key>' https://www.listicle.xyz/api/lists?organizationId=<org>
# or:
curl -s -H 'Authorization: Bearer <your-key>' https://www.listicle.xyz/api/lists?organizationId=<org>
```

To get a key: sign in to https://www.listicle.xyz as yourself, then `POST /api/user/api-key` from a session-authenticated browser. The page at https://www.listicle.xyz/bootstrap shows it inline once issued.

**Browser session (UI):** sign in normally — the session cookie carries auth. API-key endpoints accept either.

Lists in this environment (0)

No lists found.

Endpoint catalog

Read-only

GET/api/bootstrapauth: public

This endpoint. Re-call any time to refresh the contract, env, and recent lists.

curl \
  -sS \
  'https://www.listicle.xyz/api/bootstrap'
GET/api/user/api-keyauth: session

Return the caller’s API key (session auth required).

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  'https://www.listicle.xyz/api/user/api-key'
GET/api/lists?organizationId={orgId}&onlyPublic=true|false&limit={n}auth: either

List lists scoped to an organization, with optional public/own/limit filters.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  'https://www.listicle.xyz/api/lists?organizationId={orgId}&onlyPublic=true|false&limit={n}'
GET/api/lists/{id}auth: either

Return one list, including items.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  'https://www.listicle.xyz/api/lists/{id}'

Mutations

POST/api/user/api-keyauth: session

Generate or rotate the caller’s API key. Old key stops working immediately.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  -X POST \
  'https://www.listicle.xyz/api/user/api-key'
POST/api/listsauth: either

Create a list. Body: { title, description?, slug?, private, organizationId }.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  -X POST \
  'https://www.listicle.xyz/api/lists'
POST/api/lists/{id}/itemsauth: either

Append an item to a list. Body: { text, link? }.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  -X POST \
  'https://www.listicle.xyz/api/lists/{id}/items'
PATCH/api/lists/{id}/items/{itemId}auth: either

Edit an item. Body: { text?, link? }.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  -X PATCH \
  'https://www.listicle.xyz/api/lists/{id}/items/{itemId}'
DELETE/api/lists/{id}/items/{itemId}auth: either

Delete an item.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  -X DELETE \
  'https://www.listicle.xyz/api/lists/{id}/items/{itemId}'
POST/api/lists/{id}/items/{itemId}/upvoteauth: either

Toggle upvote on an item.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  -X POST \
  'https://www.listicle.xyz/api/lists/{id}/items/{itemId}/upvote'
POST/api/lists/{id}/items/{itemId}/commentsauth: either

Add a comment to an item. Body: { body }.

curl \
  -sS \
  -H 'X-API-Key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  -X POST \
  'https://www.listicle.xyz/api/lists/{id}/items/{itemId}/comments'