Branches API

The Branches API allows you to manage your database branches, including listing, creating, updating, and deleting branches. All endpoints require authentication via API key or OIDC.

Authentication

All endpoints require authentication. You can authenticate using:

• API Key: Include your API key in the Authorization header: Authorization: Bearer <your-api-key>
• OIDC: Use OIDC tokens for authentication

Required scopes for different operations:

• branch:read: Read branch information and list branches
• branch:write: Create, update, and delete branches
• credentials:read: Access branch credentials
• metrics:read: Access branch metrics

List branches

Retrieves a list of all branches within a project.

GET /organizations/{organizationID}/projects/{projectID}/branches

Summary

Returns a paginated list of branches in a project with basic metadata including ID, name, creation date, region, and public access settings.

Path parameters

Response

Status: 200 OK

{
  "branches": [
    {
      "id": "br_123",
      "name": "main",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "region": "us-east-1",
      "publicAccess": false,
      "description": "Main production branch",
      "parentID": null
    }
  ]
}

Response schema

Create branch

Creates a new branch within a project. Branches can be created from scratch or derived from an existing parent branch.

POST /organizations/{organizationID}/projects/{projectID}/branches

Summary

Creates a new database branch with specified configuration. If a parent branch is specified, the new branch inherits the parent's configuration and data. Otherwise, a new cluster is created with the specified configuration.

Path parameters

Request body

{
  "name": "staging-branch",
  "description": "Staging environment for testing",
  "parentID": "br_123",
  "configuration": {
    "image": "postgresql:17",
    "instanceType": "small",
    "instances": 1,
    "region": "us-east-1"
  },
  "scaleToZero": {
    "enabled": true,
    "idleTime": 300
  }
}

Request body parameters

Response

Status: 201 Created

{
  "id": "br_456",
  "name": "staging-branch",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "region": "us-east-1",
  "publicAccess": false,
  "description": "Staging environment for testing",
  "parentID": "br_123",
  "connectionString": "postgresql://xata_user:password@host:port/database"
}

Response schema

Get branch

Retrieves detailed information about a specific branch.

GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}

Summary

Returns comprehensive information about a branch including its configuration, status, connection details, and operational state.

Path parameters

Response

Status: 200 OK

{
  "id": "br_123",
  "name": "main",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "region": "us-east-1",
  "publicAccess": false,
  "description": "Main production branch",
  "parentID": null,
  "connectionString": "postgresql://xata_user:password@host:port/database",
  "configuration": {
    "image": "postgresql:17",
    "instanceType": "small",
    "instances": 1,
    "region": "us-east-1"
  },
  "status": {
    "instanceCount": 1,
    "instanceReadyCount": 1,
    "instances": [
      {
        "id": "inst_123",
        "status": "ready",
        "region": "us-east-1",
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "lifecycle": {
      "phase": "running",
      "message": "Branch is operational"
    }
  },
  "scaleToZero": {
    "enabled": true,
    "idleTime": 300
  }
}

Response schema

Update branch

Updates the configuration of a branch.

PATCH /organizations/{organizationID}/projects/{projectID}/branches/{branchID}

Summary

Updates branch metadata such as name and description. Note that cluster configuration changes require creating a new branch.

Path parameters

Request body

{
  "name": "updated-branch-name",
  "description": "Updated description for the branch"
}

Request body parameters

Response

Status: 200 OK

{
  "id": "br_123",
  "name": "updated-branch-name",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "region": "us-east-1",
  "publicAccess": false,
  "description": "Updated description for the branch",
  "parentID": null,
  "connectionString": "postgresql://xata_user:password@host:port/database"
}

Delete branch

Permanently deletes a branch and all its associated data.

DELETE /organizations/{organizationID}/projects/{projectID}/branches/{branchID}

Summary

Permanently removes a branch and all associated data. This action cannot be undone and will terminate all active connections.

Path parameters

Response

Status: 204 No Content

No response body is returned on successful deletion.

Get branch credentials

Retrieves credentials for accessing a branch database.

GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/credentials

Summary

Returns database credentials (username and password) for connecting to a specific branch. These credentials can be used with the connection string returned by the branch details endpoint.

Path parameters

Query parameters

Response

Status: 200 OK

{
  "username": "xata_user",
  "password": "secure_password_123"
}

Response schema

Branch Metrics

For detailed metrics and monitoring data for branches, see the Metrics API documentation.

The Metrics API provides comprehensive performance monitoring including CPU, memory, and disk usage across branch instances with support for multiple aggregation types and time-series data.

Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

{
  "id": "error_identifier",
  "message": "Human-readable error message explaining the issue"
}

Common error responses

Schema Reference

Core Data Models

BranchListMetadata

Basic branch information returned when listing branches.

BranchMetadata

Complete branch information including configuration and status details.

BranchShortMetadata

Simplified branch information returned for create/update operations.

ClusterConfiguration

Database cluster configuration including image, instance type, and region.

ScaleToZeroConfiguration

Configuration for automatic scaling to zero when branches are idle.

BranchStatus

Operational status information including instance counts and lifecycle state.

BranchCredentials

Database access credentials for a specific branch.

BranchCreationDetails

Details required when creating a new branch.

BranchUpdateDetails

Details that can be updated for an existing branch.

InstanceMetadata

Information about a specific database instance.

LifecycleInfo

Lifecycle information for a branch.