API Reference

Published posts, newest first (by publishedAt, falling back to createdAt), paginated. Post bodies are omitted here. Fetch a single post to get its Markdown.

curl "https://usebueno.com/api/v1/posts?category=engineering&limit=10" \
    -H "Authorization: Bearer $BUENO_API_KEY"

{
    "posts": [
      {
        "title": "Shipping faster with Bueno",
        "description": "How we cut our publishing loop in half.",
        "slug": "shipping-faster-with-bueno",
        "coverImageUrl": "https://usebueno.com/api/cms/assets/covers/abc123.jpg",
        "tags": ["product", "engineering"],
        "category": { "name": "Engineering", "slug": "engineering" },
        "author": {
          "name": "Ada Lovelace",
          "avatarUrl": "https://usebueno.com/api/cms/assets/authors/ada.jpg",
          "bio": "Writes about tooling."
        },
        "publishedAt": "2026-08-01 09:00:00",
        "createdAt": "2026-07-28 11:24:10"
      }
    ],
    "total": 42,
    "limit": 10,
    "offset": 0
  }

total is the count of posts matching the filters (not the page), so you can paginate until offset + limit ≥ total.

One published post by slug, including its Markdown body. Returns 404 when the slug isn't a published post in this project.

Every response carries seriesList: the series this post belongs to, each with its position and total, so a page can render “Part 3 of 8” without a second call. Add ?series=<slug> to also get a series object with prev and next: everything a guide's “← Previous / Next →” footer needs, without pulling the whole series on every post view. It's absent when the post isn't a published member of that series.

curl "https://usebueno.com/api/v1/posts/shipping-faster-with-bueno" \
    -H "Authorization: Bearer $BUENO_API_KEY"

{
    "post": {
      "title": "Shipping faster with Bueno",
      "description": "How we cut our publishing loop in half.",
      "slug": "shipping-faster-with-bueno",
      "coverImageUrl": "https://usebueno.com/api/cms/assets/covers/abc123.jpg",
      "tags": ["product", "engineering"],
      "category": { "name": "Engineering", "slug": "engineering" },
      "author": { "name": "Ada Lovelace", "avatarUrl": null, "bio": null },
      "publishedAt": "2026-08-01 09:00:00",
      "createdAt": "2026-07-28 11:24:10",
      "body": "## The old loop\n\nWe used to...",
      "seriesList": [
        { "name": "Getting Started", "slug": "getting-started", "position": 2, "total": 8 }
      ],
      "series": {
        "name": "Getting Started",
        "slug": "getting-started",
        "position": 2,
        "total": 8,
        "section": "Part 2: Going deeper",
        "prev": { "title": "Your first project", "slug": "your-first-project" },
        "next": { "title": "Scheduling a post", "slug": "scheduling-a-post" }
      }
    }
  }

Every category in the project with its published-post count. Empty categories are included with posts_count: 0, so you decide whether to show them. Subcategories come back in the same flat list, each carrying the parent_slug it hangs off. Group by it to render the tree. A parent's posts_count includes the posts in its subcategories.

curl "https://usebueno.com/api/v1/categories" \
    -H "Authorization: Bearer $BUENO_API_KEY"

{
    "categories": [
      {
        "name": "Engineering",
        "slug": "engineering",
        "description": "Build notes and postmortems.",
        "posts_count": 12
      },
      {
        "name": "Postmortems",
        "slug": "postmortems",
        "description": "What broke, and why.",
        "parent_slug": "engineering",
        "posts_count": 3
      }
    ]
  }

A series is a curated, ordered run of posts: a guide, a multi-part write-up. Where a category groups posts by subject and leaves them unordered, a series is a hand-picked reading order, so it can mix categories freely.

posts_count counts only the published members (the ones GET /series/{slug} will actually return), so an all-draft guide reads as empty instead of looking full and then coming back with nothing.

curl "https://usebueno.com/api/v1/series" \
    -H "Authorization: Bearer $BUENO_API_KEY"

{
    "series": [
      {
        "name": "Getting Started",
        "slug": "getting-started",
        "description": "Everything you need in your first week.",
        "posts_count": 8
      }
    ]
  }

One series with its posts in reading order: the guide's index page. Render them in the order returned; don't re-sort.

Only published posts come back, and position is re-indexed over them, so “part 3 of 8” always matches what a reader can open. A draft parked mid-run doesn't leave a hole in the numbering. Each entry is a Post summary (no body) plus position and an optional section: a group heading, where consecutive entries sharing one belong under it. Returns 404 for an unknown slug.

curl "https://usebueno.com/api/v1/series/getting-started" \
    -H "Authorization: Bearer $BUENO_API_KEY"

{
    "series": {
      "name": "Getting Started",
      "slug": "getting-started",
      "description": "Everything you need in your first week.",
      "posts_count": 2,
      "posts": [
        {
          "title": "Your first project",
          "slug": "your-first-project",
          "description": "Set up in five minutes.",
          "position": 0,
          "section": "Part 1: Basics",
          "tags": [],
          "publishedAt": "2026-08-01 09:00:00",
          "createdAt": "2026-07-28 11:24:10"
        },
        {
          "title": "Scheduling a post",
          "slug": "scheduling-a-post",
          "description": "Publish on your own clock.",
          "position": 1,
          "tags": [],
          "publishedAt": "2026-08-03 09:00:00",
          "createdAt": "2026-08-02 10:00:00"
        }
      ]
    }
  }

Creates a post in this project. Requires a key with Allow write turned on (Settings → Project → API Access) and must be called from your server (see Overview). Only title is required; a post defaults to a draft, so it stays invisible to the read endpoints until you publish it.

curl -X POST "https://usebueno.com/api/v1/posts" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Shipping the new editor",
      "body": "## Why\nWe rebuilt it.",
      "categoryName": "Engineering",
      "tags": ["changelog"],
      "status": "published"
    }'

Responds 201 with the created post, including the slug it was actually given:

{
    "post": {
      "id": "0b1c…",
      "title": "Shipping the new editor",
      "slug": "shipping-the-new-editor",
      "status": "published",
      "categoryName": "Engineering",
      "tags": ["changelog"]
    }
  }

Edits a post in place, addressed by its current slug. Unlike the GET, this reaches drafts and hidden posts too, so a post you created as a draft can be filled in and then published. Requires a key with Allow write turned on and must be called from your server (see Overview).

It's a partial update: every field is optional and anything you omit keeps its current value, so sending just body won't wipe the category or tags. Fields that can be emptied take an explicit null to clear them: that's what distinguishes “leave it” from “remove it”. tags replaces the whole list; pass [] to strip them.

curl -X PATCH "https://usebueno.com/api/v1/posts/shipping-the-new-editor" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "status": "published", "tags": ["changelog", "editor"] }'

Responds 200 with the updated post, or 404 when no post in the project has that slug:

{
    "post": {
      "id": "0b1c…",
      "title": "Shipping the new editor",
      "slug": "shipping-the-new-editor",
      "status": "published",
      "categoryName": "Engineering",
      "tags": ["changelog", "editor"]
    }
  }

Creates a category, or a subcategory when you pass parentSlug. Requires a key with Allow write turned on and must be called from your server (see Overview). Nesting is one level deep: a subcategory can't have subcategories.

curl -X POST "https://usebueno.com/api/v1/categories" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Postmortems",
      "description": "What broke, and why.",
      "parentSlug": "engineering"
    }'

Responds 201 with the category in the same shape GET /categories returns, including the slug it was actually given:

{
    "category": {
      "name": "Postmortems",
      "slug": "postmortems",
      "description": "What broke, and why.",
      "parent_slug": "engineering",
      "posts_count": 0
    }
  }

Renames, re-slugs, re-describes, or moves a category, addressed by its current slug. Partial like the post update: omitted fields keep their value. Posts filed under the category stay filed under it, whatever changes. Requires a key with Allow write turned on and must be called from your server.

Moves respect the one-level nesting rule, so 400 comes back if the target parent is itself a subcategory, or if the category being moved has subcategories of its own.

curl -X PATCH "https://usebueno.com/api/v1/categories/postmortems" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "description": "Incidents, in full.", "parentSlug": null }'

{
    "category": {
      "name": "Postmortems",
      "slug": "postmortems",
      "description": "Incidents, in full."
    }
  }

Deletes a category or subcategory by slug. Deleting a parent deletes its subcategories too. Posts are never deleted: the ones filed under any of the removed categories are simply left uncategorized, keeping their body, slug, tags, and publish state. Requires a key with Allow write turned on and must be called from your server. 404 when no category in the project has that slug.

curl -X DELETE "https://usebueno.com/api/v1/categories/engineering" \
    -H "Authorization: Bearer $BUENO_API_KEY"

deleted lists every slug that went away (the category plus any subcategories), so you know which urls stopped resolving:

{ "ok": true, "deleted": ["engineering", "postmortems"] }

Creates an empty series. Requires a key with Allow write turned on (Settings → Project → API Access) and must be called from your server (see Overview). Add its posts with PUT /series/{slug}.

curl -X POST "https://usebueno.com/api/v1/series" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"Getting Started","description":"Everything you need in your first week."}'

Replaces the series' posts and their order in one call. Send the whole list: there are no insert or move operations, so the result is exactly what you sent, with no server-side merge to reason about. [] empties the series. Same write-key rules as above.

Posts are addressed by slug. An unknown slug is a 404 rather than a silent skip: a typo here would quietly truncate a published guide. Drafts may be added; they stay hidden until published. An entry can be a bare slug string, or an object with a section heading.

curl -X PUT "https://usebueno.com/api/v1/series/getting-started" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"posts":[
          {"slug":"your-first-project","section":"Part 1: Basics"},
          "scheduling-a-post"
        ]}'

Reads the project's persistent Content Factory style prompts — the ones edited in the app under Content Settings → Style Prompt. These steer every generated post and cover image, distinct from a one-off style field a caller might pass for a single generation. Auth: Authorization: Bearer $BUENO_API_KEY.

curl "https://usebueno.com/api/v1/content-settings" \
    -H "Authorization: Bearer $BUENO_API_KEY"

{
    "blogPrompt": "Write like a founder explaining a decision to a peer. No em dashes.",
    "coverPrompt": "Flat vector illustration, muted pastel palette, no gradients.",
    "coverReferences": ["https://example.com/brand/cover-ref-1.png"]
  }

Updates the style prompts. Partial: an omitted field keeps its stored value; an empty string clears it. Requires a key with Allow write turned on (Settings → Project → API Access) and must be called server-side (see Overview).

curl -X PATCH "https://usebueno.com/api/v1/content-settings" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"blogPrompt":"Short paragraphs. Never open with a question."}'

Responds with the full updated state, same shape as the GET above.

Lists the project's Content Factory memory: durable style rules, either added by hand or learned from an operator's edits to a generated draft. Only active rules are folded into a generation prompt — learned rules land as suggested and are never applied until approved in the app. Auth: Authorization: Bearer $BUENO_API_KEY.

curl "https://usebueno.com/api/v1/content-memory?scope=blog&status=active" \
    -H "Authorization: Bearer $BUENO_API_KEY"

{
    "memory": [
      {
        "id": "c1b2...",
        "scope": "blog",
        "rule": "Never open a post with a rhetorical question.",
        "source": "learned",
        "status": "active",
        "postId": "8f3e...",
        "createdAt": "2026-08-02 10:14:03"
      }
    ]
  }

Adds a rule. source is always manual for rules added this way — only the app's own learn loop can mint a learned row. Requires a key with Allow write turned on and must be called server-side.

curl -X POST "https://usebueno.com/api/v1/content-memory" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"scope":"cover","rule":"Never include people in the illustration."}'

Responds 201 with the created rule. A duplicate (case-insensitive, same scope, not dismissed) or an empty rule responds 400 instead of creating a second copy.

Edits a rule's text and/or status by id — this is how an API caller approves a suggested rule ({ "status": "active" }) or dismisses one. Same write-key rules as above. 404 when the id doesn't belong to this project.

curl -X PATCH "https://usebueno.com/api/v1/content-memory" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"id":"c1b2...","status":"active"}'

Deletes a rule by ?id=. Same write-key rules as above. 404 when the id doesn't belong to this project.

curl -X DELETE "https://usebueno.com/api/v1/content-memory?id=c1b2..." \
    -H "Authorization: Bearer $BUENO_API_KEY"

Reports one page view of your site so Bueno can chart who is actually reading your content: search crawlers, AI crawlers, people arriving from an AI answer, or plain human traffic. Bueno is headless, so the visitor hits your server and never ours; this endpoint is how those visits get here.

Call it from your server, not the browser. GPTBot and Googlebot don't execute JavaScript, so a client-side beacon measures precisely the audience this endpoint exists to look past, and a request carrying an Origin header is rejected with 403 either way. Any valid key works: reporting a page view doesn't need the write scope.

Rate limited to 100 calls per 10 seconds per project. Each call carries up to 200 hits, so batching keeps you well clear of it. Over the limit you get 429.

ip and country are independent: a country is never derived from the IP, so send country if you want geography on the dashboard. The IP is used only to check a claimed crawler against the address ranges search and AI companies publish: a User-Agent saying “Googlebot” is a claim anyone can make. Both fields are optional.

curl -X POST "https://usebueno.com/api/v1/hits" \
    -H "Authorization: Bearer $BUENO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "path": "/blog/shipping-the-new-editor",
      "ua": "Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)",
      "referer": "https://chatgpt.com/"
    }'

The response reports how each hit was classified, which is the quickest way to confirm a new integration is filing traffic the way you expect:

{ "accepted": 1, "bySegment": { "ai_crawler": 1 } }

Batch when you can. An edge middleware that opens a write per page view costs more than the page does:

{ "hits": [
      { "path": "/blog/a", "ua": "…" },
      { "path": "/blog/b", "ua": "…" }
    ] }

Hits are attributed to a post by matching path against the post URL pattern set under Settings → Indexing (for example /blog/{slug}). Hits on other paths are still recorded, with no post attached: finding out an AI crawler spends its time on your pricing page is worth knowing.