API reference¶

Use the Braidplane API for automation and direct integrations. Most resources belong to an organization, and pipeline resources also name a project and environment in the URL.

This page explains the common conventions. The OpenAPI specification is the complete reference for paths, request bodies, response schemas, and validation rules.

Base URL¶

Use the API host for your Braidplane environment, without an /api suffix:

Environment	Base URL
Staging	`https://api.staging.braidplane.com`
Production	`https://api.braidplane.com`

Braidplane Alpha runs in staging. The production API is not available yet; use the staging API with test data. The public documentation's OpenAPI link describes that available staging API.

The app host is for browser sessions. Do not send API tokens to it.

Authentication¶

Send a personal access token or organization API key as a bearer token:

Authorization: Bearer <token>

Personal access tokens act as you and use your current workspace membership and permissions. Organization API keys are machine identities for automation. Give either credential only the permissions it needs, and keep it out of source files, pipeline specifications, logs, and support messages.

Create a personal access token under Account → Security → Personal access tokens. Organization administrators can create API keys with the API or CLI. The raw value is shown once.

Make a request¶

This example fetches one workspace. read -s keeps the token out of shell history and off the screen:

export BRAIDPLANE_API_URL='https://api.staging.braidplane.com'
export BRAIDPLANE_ORG='<workspace-slug>'
read -r -s -p 'Braidplane token: ' BRAIDPLANE_TOKEN
printf '\n'

curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $BRAIDPLANE_TOKEN" \
  "$BRAIDPLANE_API_URL/organizations/$BRAIDPLANE_ORG"

unset BRAIDPLANE_TOKEN

A successful response is JSON describing the workspace and its trial or plan. Use external slugs from API responses and URLs; internal database IDs are not part of the public contract.

Common resource paths¶

Task	Method and path
Get a workspace	`GET /organizations/{organization}`
List data sources	`GET /organizations/{organization}/data-sources`
Test a saved data source	`POST /organizations/{organization}/data-sources/{data_source}/test-connection`
List pipelines	`GET /organizations/{organization}/projects/{project}/pipelines`
Validate a pipeline	`POST /organizations/{organization}/projects/{project}/environments/{environment}/pipeline-validation`
Execute a deployed pipeline	`POST /organizations/{organization}/projects/{project}/environments/{environment}/pipelines/{pipeline}:execute`
List runs	`GET /organizations/{organization}/projects/{project}/environments/{environment}/runs`

The OpenAPI specification lists required bodies, permissions, and every response for these routes.

Pagination¶

List endpoints accept limit and cursor. Start without a cursor. When a response has has_more: true, pass its next_cursor to fetch the next page. Some lists also accept sort_by, order, and direction; use only the values listed for that endpoint in OpenAPI.

Errors¶

Errors use a common JSON wrapper:

{
  "error": {
    "code": "ENTITY_NAME_INVALID",
    "message": "Entity name must be between 1 and 100 characters",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Use code for program logic, show message to a person, and keep request_id when contacting support. Validation errors can also include field-level details. Never expose your bearer token in a support request.

Pipeline request behavior¶

Select project environments explicitly for environment-aware validation, deployment, binding, and run operations.
An accepted execution is asynchronous. Keep the returned run slug and poll its run resource until it reaches succeeded, failed, or canceled.
Handle validation, authentication, authorization, missing-resource, and conflict responses according to the status and schema in the OpenAPI document.