Overview
Learn what the Buildin V2 API is for, how endpoints are grouped, and the recommended integration path.
Overview
Buildin V2 API is designed for application integrations, automation scripts, internal tools, and content workflows. Use the unified /v2/* endpoints to read and write pages, blocks, databases, mind maps, users, and search results. Extension endpoints cover Markdown, file transfer, semantic search, workspace navigation, and structured mind-map workflows.
Except for the public OpenAPI metadata endpoints, every V2 endpoint uses Bearer token authentication. Before building a full integration, call GET /v2/users/me to verify the token and then follow the endpoint docs for your use case.
Basic Information
| Item | Value |
|---|---|
| Base URL | https://api.buildin.ai |
| Path prefix | /v2 |
| Authentication | Authorization: Bearer <token> |
| Data format | JSON request and response bodies. File bytes are uploaded to presigned URLs, not through V2 JSON bodies. |
| Public routes | GET /v2/openapi.json, GET /v2/openapi/meta |
| Permission model | Scopes control capabilities, for example pages.read, blocks.write, and search.read. |
Endpoint Groups
Resource Endpoints
| Resource | Typical capabilities |
|---|---|
pages |
List, create, read, update, move, and soft-delete pages. Read page properties. |
blocks |
Read blocks, read or append child blocks, update blocks, and soft-delete blocks. |
databases |
Create, read, update, and soft-delete databases; query or mutate records and manage views. |
mind-maps |
Create, read, and edit structured mind-map trees and presentation settings. |
workspace |
Read workspace metadata and list the complete sidebar directory or one section. |
users |
Fetch the current identity and list or fetch workspace members. |
search |
Search pages, databases, folders, and mind maps visible to the token. |
Extension Endpoints
| Endpoint | Use case |
|---|---|
POST /v2/search/semantic |
Find content fragments by semantic meaning. |
GET /v2/pages/:page_id/content/markdown |
Read page content as Markdown. |
POST /v2/files/upload-url |
Create a presigned upload URL and a file object for later block writes. |
GET /v2/files/download-url |
Create a temporary download URL for a file referenced by a readable block. |
POST /v2/mind-maps |
Create a mind map from a nested node tree. |
GET /v2/mind-maps/:mind_map_id |
Read the full normalized mind-map tree and settings. |
PATCH /v2/mind-maps/:mind_map_id |
Edit the title, settings, and nodes of a mind map. |
These endpoints use the same Bearer token, scope, and error model as resource endpoints.
Recommended Integration Path
- Read Authentication and Scopes to confirm token format, public routes, and the scope model.
- Run Make Your First Request and verify
GET /v2/users/mewith your token. - Read the relevant read or write endpoint docs, then use Object Models and Conventions for pagination, errors, and timestamp handling.
- Use OpenAPI when generating clients, running CI checks, or syncing API definitions.
Public Contract
Treat this documentation and the response from GET /v2/openapi.json as the public contract. The prose documentation also covers the supported soft-delete HTTP endpoints, which are deliberately omitted from the machine-readable specification so MCP and CLI discovery do not expose destructive tools. Routes, fields, and behavior absent from both surfaces should not be treated as stable public API behavior.