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, users, and search results. Extension endpoints cover Markdown, file upload, and semantic search flows.
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 |
Create, read, update, and delete pages. Read page properties. |
blocks |
Read blocks, read or append child blocks, update blocks, and delete blocks. |
databases |
Create, read, update, and delete databases. Query database records. |
users |
Fetch the current identity and fetch user profiles by ID. |
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. |
PUT /v2/pages/:page_id/content/markdown |
Replace page content with Markdown. |
POST /v2/files/upload-url |
Create a presigned upload URL and a file object for later block writes. |
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. Routes, fields, and behavior not listed here should not be treated as stable public API behavior.