API Reference
The platform ships with a full OpenAPI 3.0 specification and an interactive Swagger UI explorer.
The interactive API explorer is served directly from your running BuildPad DaaS instance. Navigate to /api-explorer in the admin UI to explore and test all endpoints interactively.
OpenAPI Specification
The raw OpenAPI JSON is available at:
GET /api/docs/openapi.jsonYou can import this URL into any API client that supports OpenAPI — Postman, Insomnia, Bruno, or any code generator.
Endpoint Groups
| Group | Base Path | Description |
|---|---|---|
| Auth | /api/auth/* | Login, logout, refresh, password reset |
| Items | /api/items/:collection | Generic CRUD for any collection |
| Users | /api/users | User management |
| Roles | /api/roles | Role management |
| Policies | /api/policies | Policy management |
| Permissions | /api/permissions | Permission rules |
| Access | /api/access | Access records (role-policy-user assignments) |
| Collections | /api/collections | Schema introspection and DDL |
| Fields | /api/fields | Column metadata and DDL |
| Relations | /api/relations | Foreign key and relation metadata |
| Files | /api/files | File upload and management |
| Folders | /api/folders | Folder management |
| Assets | /api/assets/:id | File asset serving |
| Versions | /api/versions | Content versioning |
| Workflows | /api/workflows | Workflow definitions |
| Workflow Assignments | /api/workflow-assignments | Workflow–collection assignments |
| Workflow Instances | /api/workflow-instances | Active workflow states |
| Extensions | /api/ext/* | Custom extension endpoint execution |
| Extension Management | /api/extensions | Extension CRUD, activate, deactivate |
| Schema | /api/schema/* | Snapshot, diff, apply |
| Settings | /api/settings | General, CORS, SMTP, MCP project settings |
| Utils | /api/utils/* | Hash, random, export, import, sort, cache |
| Server | /api/server/* | Ping, health, info |
| Health | /api/health | Top-level liveness probe |
| Activity | /api/activity | User activity log (admin only) |
| Revisions | /api/revisions | Read-only item change audit log (admin only) |
| Logs | /api/logs | In-memory runtime logs and SSE stream (admin only) |
| Cron | /api/cron | Scheduled cron job management (admin only) |
| Services | /api/services | Custom HTTP service definitions (admin only) |
| Scope | /api/scope | Hierarchical scope and multi-tenancy management |
| Workflow | /api/workflow | Workflow transition endpoint |
| MCP | /api/mcp | Model Context Protocol server |
Base URL
Development: http://localhost:3000
Production: https://your-domain.comAuthentication
All endpoints require a Bearer token in the Authorization header, a session cookie, or a static token. See Authentication for details.
Error Format
Two error shapes are used across the API:
Structured envelope (used by most endpoints — items, collections, settings, schema, etc.):
{
"errors": [
{
"message": "You don't have permission to access this.",
"extensions": { "code": "FORBIDDEN" }
}
]
}Simple message (used by auth, MCP settings, and a subset of utility endpoints):
{
"error": "Not authenticated"
}