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.
List branches
Retrieves a list of all branches within a project.
GET /organizations/{organizationID}/projects/{projectID}/branchesPath parameters
| Parameter | Type | Description |
|---|---|---|
| organizationID | string | Unique identifier for the organization |
| projectID | string | Unique identifier for the project |
Response
{
"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 branch",
"parentID": null
}
]
}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}/branchesPath parameters
| Parameter | Type | Description |
|---|---|---|
| organizationID | string | Unique identifier for the organization |
| projectID | string | Unique identifier for the project |
Request body
{
"name": "new-branch",
"description": "Development branch",
"parentID": "br_123",
"configuration": {
"image": "postgresql:16",
"instanceType": "standard",
"instances": 1,
"region": "us-east-1",
"storage": 10
},
"scaleToZero": {
"enabled": true,
"idleTime": 300
}
}Request body parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Human-readable name for the new branch |
| description | string | Optional description for the branch purpose or contents (max 50 characters) |
| parentID | string | If present, the branch will inherit the parent branch configuration and data |
| configuration | object | Configuration for the underlying database cluster if not inheriting from a parent |
| scaleToZero | object | Scale to zero configuration for the branch |
Response
{
"id": "br_456",
"name": "new-branch",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"region": "us-east-1",
"publicAccess": false,
"description": "Development branch",
"parentID": "br_123",
"connectionString": "postgresql://..."
}Get branch
Retrieves detailed information about a specific branch.
GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}Path parameters
| Parameter | Type | Description |
|---|---|---|
| organizationID | string | Unique identifier for the organization |
| projectID | string | Unique identifier for the project |
| branchID | string | Unique identifier for the branch |
Response
{
"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 branch",
"parentID": null,
"connectionString": "postgresql://...",
"configuration": {
"image": "postgresql:16",
"instanceType": "standard",
"instances": 1,
"region": "us-east-1",
"storage": 10
},
"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
}
}Update branch
Updates the configuration of a branch.
PATCH /organizations/{organizationID}/projects/{projectID}/branches/{branchID}Path parameters
| Parameter | Type | Description |
|---|---|---|
| organizationID | string | Unique identifier for the organization |
| projectID | string | Unique identifier for the project |
| branchID | string | Unique identifier for the branch |
Request body
{
"name": "updated-branch",
"description": "Updated description"
}Response
{
"id": "br_123",
"name": "updated-branch",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z",
"region": "us-east-1",
"publicAccess": false,
"description": "Updated description",
"parentID": null,
"connectionString": "postgresql://..."
}Delete branch
Permanently deletes a branch and all its associated data. This action cannot be undone.
DELETE /organizations/{organizationID}/projects/{projectID}/branches/{branchID}Path parameters
| Parameter | Type | Description |
|---|---|---|
| organizationID | string | Unique identifier for the organization |
| projectID | string | Unique identifier for the project |
| branchID | string | Unique identifier for the branch |
Response
Returns a 204 status code with no content on success.
Get branch credentials
Retrieves credentials for accessing a branch database.
GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/credentialsPath parameters
| Parameter | Type | Description |
|---|---|---|
| organizationID | string | Unique identifier for the organization |
| projectID | string | Unique identifier for the project |
| branchID | string | Unique identifier for the branch |
Query parameters
| Parameter | Type | Description |
|---|---|---|
| username | string | Username that the credentials are requested for (optional) |
Response
{
"username": "xata_user",
"password": "secure_password_123"
}Get branch metrics
Retrieves metrics for a specific branch over a time period.
POST /organizations/{organizationID}/projects/{projectID}/branches/{branchID}/metricsPath parameters
| Parameter | Type | Description |
|---|---|---|
| organizationID | string | Unique identifier for the organization |
| projectID | string | Unique identifier for the project |
| branchID | string | Unique identifier for the branch |
Request body
{
"start": "2024-01-01T00:00:00Z",
"end": "2024-01-01T23:59:59Z",
"metric": "cpu",
"instances": ["inst_123", "inst_456"],
"aggregations": ["avg", "max", "min"]
}Request body parameters
| Parameter | Type | Description |
|---|---|---|
| start | string (date-time) | Start time for the metrics query |
| end | string (date-time) | End time for the metrics query |
| metric | string | Metric name to query. Options: cpu, memory, disk |
| instances | array | List of instance IDs to query |
| aggregations | array | List of aggregations to apply. Options: avg, max, min |
Response
{
"start": "2024-01-01T00:00:00Z",
"end": "2024-01-01T23:59:59Z",
"metric": "cpu",
"unit": "percentage",
"series": [
{
"instance": "inst_123",
"aggregation": "avg",
"data": [
{
"timestamp": "2024-01-01T00:00:00Z",
"value": 25.5
},
{
"timestamp": "2024-01-01T01:00:00Z",
"value": 30.2
}
]
}
]
}Metric types
- cpu: CPU usage percentage
- memory: Memory usage in bytes
- disk: Disk usage in bytes
Aggregation types
- avg: Average value over the time interval
- max: Maximum value over the time interval
- min: Minimum value over the time interval