Blogs and docs

Resolve a post by its folder path, preview drafts, and manage tags and authors.

Blogs and docs are the same implementation over two separate trees. Everything here applies to both — swap /api/blogs for /api/docs.

Posts live in folders, and the natural way to read one is by the path a visitor would use:

curl -G https://api.console.buildbase.app/api/blogs/path \
  -H "Authorization: $BUILDBASE_TOKEN" \
  --data-urlencode 'path=engineering/why-we-moved-off-cron'

Before you start

Create folders and posts in the BuildBase console. Folder structure is editorial, so it is managed there rather than through the API.

Reading

Method	Path	Purpose
`GET`	`/api/blogs`	List posts, paginated, with the usual `filter`
`GET`	`/api/blogs/:id`	One post by id
`GET`	`/api/blogs/path`	One post by folder path
`GET`	`/api/blogs/tree`	The folder tree

/tree is what renders a sidebar — it returns the folder structure rather than the posts themselves, so you can build navigation without pulling every post body.

Paths

path is the folder path plus the post slug, joined with /:

engineering/why-we-moved-off-cron
└─ folder ─┘ └────── post slug ──────┘

The last segment is always the post; everything before it is folder structure. A post at the root is just its slug.

Previewing drafts

Unpublished posts are excluded by default. Add draftPreview=true to include them:

curl -G https://api.console.buildbase.app/api/blogs/path \
  -H "Authorization: $BUILDBASE_TOKEN" \
  --data-urlencode 'path=engineering/upcoming-post' \
  --data-urlencode 'draftPreview=true'

Wire this to a preview route your editors can reach, and leave it off in the path your public site renders. Since the endpoint needs a token either way, "leaving it off" means your backend decides — a visitor cannot set it themselves.

Tags and authors

Both are managed with dedicated endpoints rather than through the post body, so a retag does not rewrite the content:

Method	Path	Purpose
`PATCH`	`/api/blogs/:id/tags`	Replace the post's tags
`PATCH`	`/api/blogs/:id/authors`	Replace the post's authors

Both replace rather than append. Read the current list, add to it, and send the whole array back.

Writing

Method	Path	Purpose
`POST`	`/api/blogs`	Create a post
`PATCH`	`/api/blogs/:id`	Update a post
`DELETE`	`/api/blogs/:id`	Delete a post

The console is the expected authoring surface. The write endpoints are for migrations and syncing from another system — importing an existing blog, for instance.

Rendering on a public site

These endpoints need a token, so the browser never calls them. Two workable shapes:

Build time. Fetch posts during your site build and render static pages. Fastest, and the token stays in CI.
Server-side. Fetch in a server component or route handler, cache the result, and serve HTML. Use this when editors need changes live without a rebuild.

Either way the token stays server-side. See the admin API for token handling.

Next Steps

Content overview — the other content types.
Assets — images embedded in posts.