API Overview

Buildable provides a comprehensive REST API for managing projects, tasks, and AI integrations programmatically.

Base URL

https://bldbl.dev/api

Authentication

All API requests require authentication using API keys. You can generate API keys from your project's Integrations page.

API Key Authentication

Include your API key in the Authorization header:

Authorization: Bearer bp_your_api_key_here

Rate Limiting

• Free tier: 100 requests per hour
• Pro tier: 1000 requests per hour
• Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Response Format

All API responses follow a consistent format:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "title",
      "reason": "Title is required"
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

Core Endpoints

Projects

• GET /projects - List user's projects
• POST /projects - Create a new project
• GET /projects/{id} - Get project details
• PATCH /projects/{id} - Update project
• DELETE /projects/{id} - Delete project

Tasks

• GET /projects/{id}/tasks - List project tasks
• POST /projects/{id}/tasks - Create a task
• PATCH /tasks/{id} - Update task
• DELETE /tasks/{id} - Delete task

Discussions

• GET /projects/{id}/discussions - List discussions
• POST /projects/{id}/discussions - Create discussion
• POST /discussions/{id}/respond - Add response

API Keys

• GET /api-keys - List your API keys
• POST /api-keys - Generate new API key
• DELETE /api-keys/{id} - Revoke API key

MCP Integration

Buildable supports the Model Context Protocol (MCP) for AI assistant integrations:

• Protocol: MCP v1.0
• Transport: WebSocket and HTTP
• Authentication: API key-based
• Capabilities: Read/write access to projects and tasks

Learn more in our MCP Integration Guide.

Error Codes

Code	Description
UNAUTHORIZED	Invalid or missing API key
FORBIDDEN	Insufficient permissions
NOT_FOUND	Resource not found
VALIDATION_ERROR	Invalid request data
RATE_LIMITED	Too many requests
INTERNAL_ERROR	Server error

Support

For API support:

• 📧 Email: api-support@bldbl.dev
• 💬 Discord: #api-help
• 📖 Documentation: This site
• 🐛 Report Issues: GitHub Issues