API Reference

The Backbuild API gives your applications, scripts, and AI agents programmatic access to everything the platform does. This page is the starting point: it teaches the contract every endpoint shares, walks you through your first successful call, and points you to the guide for each capability.

After reading this page you will be able to: reach the API, authenticate, make a first call in a few minutes, read the uniform response envelope, handle any error by its machine-readable code, back off correctly on a rate limit, and page through a list. Everything below applies to every endpoint unless a specific guide says otherwise.

Base URL

https://api.backbuild.ai/v1

Every path in these guides is relative to that base. All request and response bodies are JSON. Send Content-Type: application/json on any request that carries a body.

Authentication

Almost every request carries a Bearer token in the Authorization header. There is no cookie-based or ambient authentication for the API: if the header is absent the request is unauthenticated, full stop.

Authorization: Bearer YOUR_TOKEN

There are two kinds of token, and you choose by how the caller runs:

Both go in the same Authorization: Bearer header. The organization every request acts on is resolved from the credential itself: it is never passed in the body or the query string, and a credential can never reach an organization it is not bound to.

Endpoints That Need No Auth

Only two endpoints are public. Everything else requires a token. Use these to verify connectivity before you have a credential in hand:

Your First Call

Start with the no-auth health check to confirm you can reach the API, then make an authenticated call. This is the fastest path from zero to a working request.

# 1. Reach the API (no auth needed)
curl https://api.backbuild.ai/v1/health

# 2. Make an authenticated call with an API key
curl https://api.backbuild.ai/v1/projects \
  -H "Authorization: Bearer bb_live_abc123_yourSecret"

A successful call returns the standard envelope described next. If you get a 401, the token is missing, malformed, or expired; if you get a 403, the token is valid but lacks the scope or role for that action. See API Keys to create a scoped key, or Authentication for the user token flow.

Response Envelope

Every endpoint returns the same envelope, so you write one parser, not one per call. On success, success is true and the payload is under data. A single-record action returns the same shape as a list action; only the contents of data differ.

{
  "success": true,
  "data": { /* the requested resource, or an array of them */ }
}

On failure, success is false and the details live under error as a stable machine-readable code and a human-readable message. Branch your handling on error.code, never on the message text (messages may change; the code is the contract).

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input"
  }
}

Error Codes

All errors use the envelope above. The HTTP status tells you the class of problem; the code tells you exactly what to do.

Some endpoints return a more specific code inside the same shape (for example, the authentication endpoints return codes such as AUTH_INVALID_CREDENTIALS). Treat any code you do not recognize by its HTTP status class: 4xx means fix the request, 5xx means retry with backoff.

Rate Limiting

Requests are rate limited per credential and per endpoint; authentication endpoints are stricter. Every response carries your current budget so you can throttle proactively rather than wait to be rejected.

When you receive a 429, wait the number of seconds in Retry-After before retrying. Build clients to back off exponentially with jitter rather than to loop immediately, and slow down as X-RateLimit-Remaining approaches zero. Published request ceilings for your plan are on the pricing page.

Pagination

List endpoints page with limit and offset query parameters and return a pagination block alongside the data. Request the first page by omitting offset (or sending offset=0); fetch the next page by increasing offset by your limit, not by the number of rows the last page happened to return.

# First page
GET /v1/projects?limit=20

# Next page (offset advances by the limit, not by rows returned)
GET /v1/projects?limit=20&offset=20

{
  "success": true,
  "data": [ /* ...up to `limit` items... */ ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Stop when has_more is false. The default and maximum limit are stated on each list endpoint (commonly a maximum of 100).

Cross-Origin Requests (CORS)

Browser calls are governed by a CORS allowlist: only approved web origins receive an Access-Control-Allow-Origin grant, so a script on another site cannot read your API responses. If a browser integration is blocked by CORS, it is calling from an origin that is not on the allowlist; move the call server-side. Server-to-server clients such as curl or a backend do not send an Origin header and are never subject to CORS. Authentication is always Bearer-token based, never cookies, so the safe pattern for a browser app is to keep the credential on your own server and proxy the call.

Endpoint Categories

Select a category for detailed, teaching-grade documentation:

Full Endpoint Reference

For the machine-generated, per-operation reference (request and response schemas for every endpoint), see the Endpoint Reference (OpenAPI). It is generated from the published OpenAPI specification and stays in lock-step with the live API.

Frequently Asked Questions