REST API reference

Reads are anonymous and return only live listings. Creating a product needs a personal API key from API keys and creates a normal private owner-bound draft.

Send POST /api/v1/tools with Authorization: Bearer lb_… and an Idempotency-Key. The response contains the private draft and editor URL. API clients cannot publish, pay, submit for review, or verify a badge.

Badge verification proves the listing’s site displayed the ListBulb badge; it is separate from editorial curation and Featured placement.

• GET /api/v1/tools — browse or filter by q, category, and tag.
• GET /api/v1/tools/:slug — retrieve one live tool.
• GET /api/v1/categories and /tags — list active taxonomy.
• POST /api/v1/tools — create an owner-bound private draft with an API key and idempotency key. Category is optional while drafting; if supplied it must be valid. Choose a category in the editor before selecting a plan or submitting. One to four public screenshot URLs are optional; otherwise ListBulb uses the product’s Open Graph image.
• GET /api/v1/openapi.json — machine-readable API description.

Reads allow browser CORS without credentials. Draft creation accepts an API key and is limited to 10 new drafts per key per day; clients should respect 429, Retry-After, and cache headers.

curl -X POST https://www.listbulb.com/api/v1/tools \
  -H "Authorization: Bearer lb_your_secret" \
  -H "Idempotency-Key: a-unique-key-per-product" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme","headline":"A focused workspace","description":"At least 200 characters describing the product, the intended customer, and what makes it useful. This text is deliberately long enough to meet ListBulb listing requirements before a human completes the draft in the editor.","websiteUrl":"https://acme.example","screenshotUrls":["https://acme.example/screenshot.png"],"category":"productivity"}'

A successful request returns 201 with { data: { slug, status: "DRAFT", editorUrl } }. Replaying the same key and body returns the same draft; reusing it with changed data returns 409 IDEMPOTENCY_CONFLICT.

Request one live product by its stable listing slug. Draft, rejected, unlisted, and private submissions return 404 TOOL_NOT_FOUND and are never exposed here.

curl "https://www.listbulb.com/api/v1/tools/notion"

Every successful response uses the standard { data, meta } envelope:

{
  "data": {
    "slug": "notion",
    "name": "Notion",
    "websiteUrl": "https://www.notion.so/",
    "listbulbUrl": "https://www.listbulb.com/tools/notion",
    "listingHeadline": "One workspace for every team",
    "description": "A connected workspace for docs, projects, and knowledge.",
    "logoUrl": "https://cdn.example.com/notion-logo.png",
    "imageUrl": null,
    "category": { "slug": "productivity", "name": "Productivity" },
    "tags": [{ "slug": "notes", "name": "Notes" }],
    "listedAt": "2026-09-20T10:00:00.000Z",
    "featured": false,
    "verification": {
      "badgeVerified": true,
      "badgeVerifiedAt": "2026-09-20T10:00:00.000Z"
    }
  },
  "meta": { "apiVersion": "v1" }
}

• websiteUrl is the product’s submitted canonical website; listbulbUrl is its public ListBulb detail page.
• listingHeadline, description, logoUrl, imageUrl, and listedAt may be null.
• category is exactly one primary taxonomy object; tags is always an array and may be empty.
• featured is a current editorial placement. verification.badgeVerified means the owner demonstrated badge/domain control; neither value implies an endorsement.

Errors use { error: { code, message } }. Invalid slugs return 400 INVALID_SLUG; a missing or non-live product returns 404 TOOL_NOT_FOUND.

For crawler-oriented discovery, use the catalog guide, llms.txt, sitemap, or RSS feed.