Branches API

Manage database branches and their settings

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

ParameterTypeRequiredDescription
organizationIDstringYesUnique identifier for the organization
projectIDstringYesUnique identifier for the project

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

FieldTypeDescription
branchesarrayArray of branch objects
idstringUnique identifier for the branch
namestringHuman-readable name for the branch
createdAtstring (date-time)Timestamp when the branch was created
updatedAtstring (date-time)Timestamp when the branch was last updated
regionstringGeographic region where the branch is deployed
publicAccessbooleanWhether the branch allows public access without authentication
descriptionstringOptional description of the branch purpose or contents
parentIDstringIdentifier of the parent branch if derived, null otherwise

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

ParameterTypeRequiredDescription
organizationIDstringYesUnique identifier for the organization
projectIDstringYesUnique identifier for the project

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

ParameterTypeRequiredDescription
namestringYesHuman-readable name for the new branch (max 50 characters, pattern: ^[a-zA-Z0-9]+[a-zA-Z0-9- ]*$)
descriptionstringNoOptional description for the branch purpose or contents (max 50 characters)
parentIDstringNoIf present, the branch will inherit the parent branch configuration and data
configurationClusterConfigurationNoConfiguration for the underlying database cluster if not inheriting from a parent
scaleToZeroScaleToZeroConfigurationNoScale to zero configuration for the branch

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

FieldTypeDescription
idstringUnique identifier for the created branch
namestringName of the branch
createdAtstring (date-time)Timestamp when the branch was created
updatedAtstring (date-time)Timestamp when the branch was last updated
regionstringGeographic region where the branch is deployed
publicAccessbooleanWhether the branch allows public access
descriptionstringDescription of the branch
parentIDstringIdentifier of the parent branch if derived
connectionStringstringDatabase connection string for the branch

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

ParameterTypeRequiredDescription
organizationIDstringYesUnique identifier for the organization
projectIDstringYesUnique identifier for the project
branchIDstringYesUnique identifier for the branch

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

FieldTypeDescription
idstringUnique identifier for the branch
namestringHuman-readable name for the branch
createdAtstring (date-time)Timestamp when the branch was created
updatedAtstring (date-time)Timestamp when the branch was last updated
regionstringGeographic region where the branch is deployed
publicAccessbooleanWhether the branch allows public access
descriptionstringDescription of the branch
parentIDstringIdentifier of the parent branch if derived
connectionStringstringDatabase connection string for the branch
configurationClusterConfigurationConfiguration details for the underlying database cluster
statusBranchStatusCurrent operational status of the branch
scaleToZeroScaleToZeroConfigurationScale to zero configuration for the branch

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

ParameterTypeRequiredDescription
organizationIDstringYesUnique identifier for the organization
projectIDstringYesUnique identifier for the project
branchIDstringYesUnique identifier for the branch

Request body

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

Request body parameters

ParameterTypeRequiredDescription
namestringNoNew name for the branch
descriptionstringNoNew description for the branch

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

ParameterTypeRequiredDescription
organizationIDstringYesUnique identifier for the organization
projectIDstringYesUnique identifier for the project
branchIDstringYesUnique identifier for the branch

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

ParameterTypeRequiredDescription
organizationIDstringYesUnique identifier for the organization
projectIDstringYesUnique identifier for the project
branchIDstringYesUnique identifier for the branch

Query parameters

ParameterTypeRequiredDescription
usernamestringNoUsername that the credentials are requested for (optional)

Response

Status: 200 OK

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

Response schema

FieldTypeDescription
usernamestringUsername for accessing the branch database
passwordstringPassword for accessing the branch database

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

StatusError TypeDescription
400BadRequestErrorRequest was malformed or contained invalid parameters
401AuthorizationErrorAuthentication failed or is missing
404GenericErrorRequested resource does not exist
5XXGenericErrorServer error occurred

Schema Reference

Core Data Models

BranchListMetadata

Basic branch information returned when listing branches.

FieldTypeRequiredDescription
idstringYesUnique identifier for the branch
namestringYesHuman-readable name for the branch
createdAtstring (date-time)YesTimestamp when the branch was created
updatedAtstring (date-time)YesTimestamp when the branch was last updated
regionstringYesGeographic region where the branch is deployed
publicAccessbooleanYesWhether the branch allows public access without authentication
descriptionstringNoOptional description of the branch purpose or contents
parentIDstringNoIdentifier of the parent branch if this is a derived branch, null otherwise

BranchMetadata

Complete branch information including configuration and status details.

FieldTypeRequiredDescription
idstringYesUnique identifier for the branch
namestringYesHuman-readable name for the branch
createdAtstring (date-time)YesTimestamp when the branch was created
updatedAtstring (date-time)YesTimestamp when the branch was last updated
regionstringYesGeographic region where the branch is deployed
statusBranchStatusYesCurrent operational status of the branch
connectionStringstringYesDatabase connection string for accessing this branch
configurationClusterConfigurationYesConfiguration details for the underlying database cluster
publicAccessbooleanYesWhether the branch allows public access without authentication
scaleToZeroScaleToZeroConfigurationYesScale to zero configuration for the branch
descriptionstringNoOptional description of the branch purpose or contents
parentIDstringNoIdentifier of the parent branch if this is a derived branch, null otherwise

BranchShortMetadata

Simplified branch information returned for create/update operations.

FieldTypeRequiredDescription
idstringYesUnique identifier for the branch
namestringYesHuman-readable name for the branch
createdAtstring (date-time)YesTimestamp when the branch was created
updatedAtstring (date-time)YesTimestamp when the branch was last updated
regionstringYesGeographic region where the branch is deployed
publicAccessbooleanYesWhether the branch allows public access without authentication
connectionStringstringNoDatabase connection string for accessing this branch
descriptionstringNoOptional description of the branch purpose or contents
parentIDstringNoIdentifier of the parent branch if this is a derived branch, null otherwise

ClusterConfiguration

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

FieldTypeRequiredDescription
imagestringYesDatabase image to use (e.g., "postgresql:17")
instanceTypestringYesInstance type for the database cluster
instancesintegerYesNumber of database instances
regionstringYesGeographic region for deployment

ScaleToZeroConfiguration

Configuration for automatic scaling to zero when branches are idle.

FieldTypeRequiredDescription
enabledbooleanYesWhether scale to zero is enabled
idleTimeintegerYesTime in seconds before scaling to zero when idle

BranchStatus

Operational status information including instance counts and lifecycle state.

FieldTypeRequiredDescription
instanceCountintegerYesTotal number of instances for the branch
instanceReadyCountintegerYesNumber of instances that are ready
instancesarrayYesArray of instance objects with status information
lifecycleobjectYesLifecycle information including phase and message

BranchCredentials

Database access credentials for a specific branch.

FieldTypeRequiredDescription
usernamestringYesUsername for accessing the branch database
passwordstringYesPassword for accessing the branch database

BranchCreationDetails

Details required when creating a new branch.

FieldTypeRequiredDescription
namestringYesHuman-readable name for the new branch
descriptionstringNoOptional description for the branch purpose or contents (max 50 characters, pattern: ^[a-zA-Z0-9]+[a-zA-Z0-9- ]*$)
parentIDstringNoIf present, the branch will inherit the parent branch configuration and data
configurationClusterConfigurationNoConfiguration for the underlying database cluster if not inheriting from a parent
scaleToZeroScaleToZeroConfigurationNoScale to zero configuration for the branch

BranchUpdateDetails

Details that can be updated for an existing branch.

FieldTypeRequiredDescription
namestringNoNew name for the branch
descriptionstringNoNew description for the branch

InstanceMetadata

Information about a specific database instance.

FieldTypeRequiredDescription
idstringYesUnique identifier for the instance
statusstringYesCurrent status of the instance
regionstringYesGeographic region where the instance is deployed
createdAtstring (date-time)YesTimestamp when the instance was created

LifecycleInfo

Lifecycle information for a branch.

FieldTypeRequiredDescription
phasestringYesCurrent lifecycle phase (e.g., "running", "starting", "stopping")
messagestringYesHuman-readable message describing the current state