### Install and Authenticate Xata CLI

Source: https://github.com/xataio/xata/blob/main/CONTRIBUTING.md

Commands to install the Xata CLI, authenticate with a local profile, and switch to that profile.

```bash
# Install CLI
curl -fsSL https://xata.io/install.sh | bash

# Authenticate to a local profile. Sign in with email dev@xata.tech and password Xata1234!
xata auth login --profile local --env local --force

# Set the profile
xata auth switch local
```

--------------------------------

### Install and Authenticate Xata CLI

Source: https://github.com/xataio/xata/blob/main/README.md

Installs the Xata CLI and authenticates to a local development profile. Ensure you use the correct email and password for local authentication.

```bash
# Install CLI
curl -fsSL https://xata.io/install.sh | bash
```

```bash
# Authenticate to a local profile. Sign in with email dev@xata.tech and password Xata1234!
xata auth login --profile local --env local --force
```

```bash
# Set the profile
xata auth switch local
```

--------------------------------

### Setup Local Development Environment

Source: https://context7.com/xataio/xata/llms.txt

Commands to initialize a local development environment using Kind, Tilt, and the Xata CLI.

```bash
# Prerequisites: Docker, Kind, Tilt

# Step 1: Create Kind cluster
kind create cluster --wait 10m

# Step 2: Deploy via Tilt (watches for changes)
tilt up

# Wait for all resources to be ready (first run may take time for image downloads)

# Step 3: Install and authenticate CLI
curl -fsSL https://xata.io/install.sh | bash
xata auth login --profile local --env local --force
# Sign in with: email=dev@xata.tech password=Xata1234!
xata auth switch local

# Step 4: Create your first project and branch
xata project create --name my-project
xata branch create --name main --project my-project

# Step 5: Create a child branch for development
xata branch create --name dev --parent main --project my-project

# Connect and run queries
psql "$(xata branch connection-string --name dev --project my-project)"
```

--------------------------------

### Connect using psql

Source: https://context7.com/xataio/xata/llms.txt

Example of how to use retrieved branch credentials to connect to the database using the psql command-line tool.

```bash
# Use credentials to connect via psql
psql "postgres://postgres:generated_secure_password_xyz@br_main_abc123.us-east-1.xata.tech:5432/postgres"
```

--------------------------------

### Get Specific Project Details

Source: https://context7.com/xataio/xata/llms.txt

Fetch detailed information about a particular project by providing its ID in the URL.

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/projects/{projectID}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### List Projects in an Organization

Source: https://context7.com/xataio/xata/llms.txt

Retrieve a list of all projects within a specified organization using the GET request.

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### GET /organizations/{orgID}/projects/{projectID}/branches/{branchID}/postgres-config

Source: https://context7.com/xataio/xata/llms.txt

Retrieves detailed PostgreSQL configuration parameters for a branch.

```APIDOC
## GET /organizations/{orgID}/projects/{projectID}/branches/{branchID}/postgres-config

### Description
Retrieves detailed PostgreSQL configuration parameters for a branch including types, acceptable ranges, default values, and current values.

### Method
GET

### Endpoint
https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}/postgres-config

### Response
#### Success Response (200)
- **parameters** (array) - List of configuration parameters
```

--------------------------------

### Get PostgreSQL Configuration Details

Source: https://context7.com/xataio/xata/llms.txt

Fetches detailed PostgreSQL configuration parameters for a branch, including their types, acceptable ranges, default values, and current settings. This helps in understanding and tuning database behavior.

```bash
# Get PostgreSQL configuration details
curl -X GET "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}/postgres-config" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### GET /organizations/{orgID}/projects/{projectID}/branches/{branchID}/credentials

Source: https://context7.com/xataio/xata/llms.txt

Retrieves database credentials for connecting to a branch.

```APIDOC
## GET /organizations/{orgID}/projects/{projectID}/branches/{branchID}/credentials

### Description
Retrieves database credentials for connecting to a branch. Returns username and password for PostgreSQL authentication.

### Method
GET

### Endpoint
https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}/credentials

### Parameters
#### Query Parameters
- **username** (string) - Optional - Specific username to retrieve credentials for.

### Response
#### Success Response (200)
- **username** (string) - Database username
- **password** (string) - Database password
```

--------------------------------

### Get Organization Details

Source: https://context7.com/xataio/xata/llms.txt

Fetch details for a specific organization using its ID. The 'Authorization' header must contain a valid API key.

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Get Branch Information

Source: https://context7.com/xataio/xata/llms.txt

Retrieves detailed information about a specific branch, including its status, connection string, and configuration. Requires organization ID, project ID, and branch ID.

```bash
# Get detailed branch information
curl -X GET "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Get Branch CPU Metrics

Source: https://context7.com/xataio/xata/llms.txt

Retrieves CPU performance metrics for specified instances within a branch over a given time range. Allows for aggregation of data using average and maximum values.

```bash
# Get branch CPU metrics
curl -X POST "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-15T00:00:00Z",
    "end": "2024-01-15T12:00:00Z",
    "metric": "cpu",
    "instances": ["main-1", "main-2"],
    "aggregations": ["avg", "max"]
  }'
```

--------------------------------

### Get Branch Credentials

Source: https://context7.com/xataio/xata/llms.txt

Retrieves the PostgreSQL username and password for a specific branch. These credentials are required for direct database connections.

```bash
# Get branch credentials
curl -X GET "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}/credentials" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### GET /organizations/{orgID}/projects/{projectID}/branches/{branchID}

Source: https://context7.com/xataio/xata/llms.txt

Retrieves detailed branch information including status, connection string, and configuration.

```APIDOC
## GET /organizations/{orgID}/projects/{projectID}/branches/{branchID}

### Description
Retrieves detailed branch information including status, connection string, and configuration.

### Method
GET

### Endpoint
https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}

### Parameters
#### Path Parameters
- **orgID** (string) - Required - The organization identifier.
- **projectID** (string) - Required - The project identifier.
- **branchID** (string) - Required - The branch identifier.

### Response
#### Success Response (200)
- **id** (string) - Branch ID
- **name** (string) - Branch name
- **status** (object) - Cluster status details
- **connectionString** (string) - PostgreSQL connection string
- **configuration** (object) - Branch configuration settings
- **scaleToZero** (object) - Hibernation settings
```

--------------------------------

### Projects API - List, Get, Update, and Delete Projects

Source: https://context7.com/xataio/xata/llms.txt

Retrieves all projects within an organization, detailed information about a specific project, updates a project's configuration, or deletes a project.

```APIDOC
## GET /organizations/{organizationID}/projects

### Description
Retrieves a list of all projects within an organization.

### Method
GET

### Endpoint
/organizations/{organizationID}/projects

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.

### Response
#### Success Response (200)
- **projects** (array) - A list of projects.
  - **id** (string) - The ID of the project.
  - **name** (string) - The name of the project.
  - **createdAt** (string) - The timestamp when the project was created.
  - **updatedAt** (string) - The timestamp when the project was last updated.

#### Response Example
```json
{
  "projects": [
    {"id": "prj_abc123", "name": "production-app", "createdAt": "...", "updatedAt": "..."},
    {"id": "prj_def456", "name": "staging-app", "createdAt": "...", "updatedAt": "..."}
  ]
}
```

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

### Description
Retrieves detailed information about a specific project.

### Method
GET

### Endpoint
/organizations/{organizationID}/projects/{projectID}

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.
- **projectID** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **id** (string) - The ID of the project.
- **name** (string) - The name of the project.
- **createdAt** (string) - The timestamp when the project was created.
- **updatedAt** (string) - The timestamp when the project was last updated.
- **configuration** (object) - The configuration of the project.

#### Response Example
```json
{
  "id": "prj_abc123",
  "name": "my-project",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "configuration": {}
}
```

## PATCH /organizations/{organizationID}/projects/{projectID}

### Description
Updates the configuration of a specific project.

### Method
PATCH

### Endpoint
/organizations/{organizationID}/projects/{projectID}

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.
- **projectID** (string) - Required - The ID of the project.

#### Request Body
- **name** (string) - Optional - The new name for the project.
- **configuration** (object) - Optional - Project configuration settings to update.
  - **scaleToZero** (object) - Optional - Scale-to-zero configuration.
    - **childBranches** (object) - Optional - Configuration for child branches.
      - **enabled** (boolean) - Optional - Whether scale-to-zero is enabled for child branches.
      - **inactivityPeriodMinutes** (integer) - Optional - Inactivity period in minutes for child branches.

### Request Example
```json
{
  "name": "renamed-project",
  "configuration": {
    "scaleToZero": {
      "childBranches": {"enabled": true, "inactivityPeriodMinutes": 20}
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the updated project.
- **name** (string) - The name of the project.
- **createdAt** (string) - The timestamp when the project was created.
- **updatedAt** (string) - The timestamp when the project was last updated.
- **configuration** (object) - The updated configuration of the project.

#### Response Example
```json
{
  "id": "prj_abc123",
  "name": "renamed-project",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z",
  "configuration": {
    "scaleToZero": {
      "childBranches": {"enabled": true, "inactivityPeriodMinutes": 20}
    }
  }
}
```

## DELETE /organizations/{organizationID}/projects/{projectID}

### Description
Deletes a project. WARNING: This action deletes all branches and data within the project.

### Method
DELETE

### Endpoint
/organizations/{organizationID}/projects/{projectID}

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.
- **projectID** (string) - Required - The ID of the project to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of deletion.

#### Response Example
```json
{
  "message": "Project prj_abc123 deleted successfully."
}
```
```

--------------------------------

### Get Branch Credentials for Specific User

Source: https://context7.com/xataio/xata/llms.txt

Retrieves credentials for a specific username associated with a branch. Useful if you manage multiple application users.

```bash
# Get credentials for specific username
curl -X GET "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}/credentials?username=app_user" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Deploy via Tilt

Source: https://github.com/xataio/xata/blob/main/README.md

Initiates the deployment of resources using Tilt. The first run may take longer due to image downloads.

```bash
tilt up
```

--------------------------------

### Query Deployment Regions and Instance Types

Source: https://context7.com/xataio/xata/llms.txt

Retrieve available regions, instance configurations, and PostgreSQL images for branch deployment.

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/regions" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/instanceTypes?region=us-east-1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/images?region=us-east-1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Create Project and Branch

Source: https://github.com/xataio/xata/blob/main/CONTRIBUTING.md

Commands to initialize a new Xata project and create a child branch.

```bash
# Create project and main branch
$ xata project create --name my-project

# Create a child branch
$ xata branch create
```

--------------------------------

### Create a New Project

Source: https://context7.com/xataio/xata/llms.txt

Use this command to create a new project within an organization via the REST API. Configure scale-to-zero behavior and IP filtering rules.

```bash
curl -X POST "https://api.xata.io/organizations/{organizationID}/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-application",
    "configuration": {
      "scaleToZero": {
        "baseBranches": {
          "enabled": false,
          "inactivityPeriodMinutes": 30
        },
        "childBranches": {
          "enabled": true,
          "inactivityPeriodMinutes": 15
        }
      },
      "ipFiltering": {
        "enabled": true,
        "cidr": [
          {"cidr": "10.0.0.0/8", "description": "Internal network"},
          {"cidr": "192.168.1.0/24", "description": "Office VPN"}
        ]
      }
    }
  }'
```

--------------------------------

### Create Kind Cluster

Source: https://github.com/xataio/xata/blob/main/README.md

Use this command to create a local Kubernetes cluster using Kind. The --wait flag ensures the cluster is ready before proceeding.

```bash
kind create cluster --wait 10m
```

--------------------------------

### Manage Xata Projects and Branches via CLI

Source: https://context7.com/xataio/xata/llms.txt

Standard CLI commands for authentication, project creation, and branch lifecycle management.

```bash
# Install the CLI
curl -fsSL https://xata.io/install.sh | bash

# Authenticate to Xata (for local development)
xata auth login --profile local --env local --force

# Switch authentication profiles
xata auth switch local

# Create a new project
xata project create --name my-project

# List projects
xata project list

# Create the main branch
xata branch create --name main --project my-project

# Create a child branch (CoW copy from parent)
xata branch create --name feature-branch --parent main --project my-project

# List branches in a project
xata branch list --project my-project

# Get branch details
xata branch describe --name main --project my-project

# Connect to a branch via psql
xata branch connect --name main --project my-project

# Delete a branch
xata branch delete --name feature-branch --project my-project
```

--------------------------------

### Create Organization

Source: https://context7.com/xataio/xata/llms.txt

Create a new organization with a specified name. The API key must have the necessary permissions.

```bash
curl -X POST "https://api.xata.io/organizations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Project Inc"}'
```

--------------------------------

### Cluster Configuration Options

Source: https://context7.com/xataio/xata/llms.txt

Defines the settings for a PostgreSQL cluster, such as the number of instances, storage size, image name, CPU and memory allocation, hibernation state, scale-to-zero configuration, PostgreSQL parameters, and preloaded libraries.

```protobuf
// Cluster configuration options
message ClusterConfiguration {
  int32 num_instances = 1;           // 1-5 instances
  int32 storage_size = 2;            // Storage in GiB
  string image_name = 3;             // PostgreSQL image
  string vcpu_request = 8;           // CPU request
  string vcpu_limit = 9;             // CPU limit
  string memory = 5;                 // Memory allocation
  bool hibernate = 6;                // Hibernation state
  ScaleToZero scale_to_zero = 7;     // Scale-to-zero config
  map<string, string> postgres_configuration_parameters = 10;
  repeated string preload_libraries = 11;
}
```

--------------------------------

### Create a Child Branch (CoW Copy)

Source: https://context7.com/xataio/xata/llms.txt

Create a new child branch that is an instant Copy-on-Write clone of a parent branch. Configure scale-to-zero behavior.

```bash
curl -X POST "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "feature-user-auth",
    "description": "Feature branch for auth",
    "mode": "inherit",
    "parentID": "br_main_abc123",
    "scaleToZero": {
      "enabled": true,
      "inactivityPeriodMinutes": 15
    }
  }'
```

--------------------------------

### Create a Base Branch

Source: https://context7.com/xataio/xata/llms.txt

Create a new base branch with custom PostgreSQL configuration, including region, storage, instance type, image, replicas, and parameters.

```bash
curl -X POST "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main",
    "description": "Production database",
    "mode": "custom",
    "configuration": {
      "region": "us-east-1",
      "storage": 100,
      "instanceType": "db.t3.medium",
      "image": "postgres:16",
      "replicas": 1,
      "postgresConfigurationParameters": {
        "max_connections": "200",
        "shared_buffers": "256MB"
      },
      "preloadLibraries": ["pg_stat_statements"]
    },
    "scaleToZero": {
      "enabled": false,
      "inactivityPeriodMinutes": 30
    }
  }'
```

--------------------------------

### Create Xata Project and Branch

Source: https://github.com/xataio/xata/blob/main/README.md

Commands to create a new Xata project and its main branch, followed by creating a child branch for development.

```bash
# Create project and main branch
$ xata project create --name my-project
```

```bash
# Create a child branch
$ xata branch create
```

--------------------------------

### Create Scoped API Key

Source: https://context7.com/xataio/xata/llms.txt

Generate a new API key with specific scopes, expiry date, and associated projects/branches. The 'Authorization' header must contain a valid API key.

```bash
curl -X POST "https://api.xata.io/organizations/{organizationID}/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key",
    "expiry": "2025-01-01T00:00:00Z",
    "scopes": ["branch:read", "branch:write", "credentials:read"],
    "projects": ["prj_abc123", "prj_def456"],
    "branches": ["br_main_xyz"]
  }'
```

--------------------------------

### Regions and Instance Types API

Source: https://context7.com/xataio/xata/llms.txt

Endpoints for querying available deployment regions and instance types for creating branches.

```APIDOC
## GET /organizations/{organizationID}/regions

### Description
Lists all available deployment regions.

### Method
GET

### Endpoint
/organizations/{organizationID}/regions

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.

### Request Example
```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/regions" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **regions** (array) - A list of available regions.
  - **id** (string) - The identifier of the region.
  - **publicAccess** (boolean) - Indicates if public access is enabled for the region.
  - **backupsEnabled** (boolean) - Indicates if backups are enabled for the region.
  - **organizationId** (string or null) - The organization ID associated with the region, if any.

#### Response Example
```json
{
  "regions": [
    {"id": "us-east-1", "publicAccess": true, "backupsEnabled": true, "organizationId": null},
    {"id": "eu-west-1", "publicAccess": true, "backupsEnabled": true, "organizationId": null}
  ]
}
```
```

```APIDOC
## GET /organizations/{organizationID}/instanceTypes

### Description
Lists available instance types for a specific region.

### Method
GET

### Endpoint
/organizations/{organizationID}/instanceTypes

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.

#### Query Parameters
- **region** (string) - Required - The ID of the region to list instance types for.

### Request Example
```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/instanceTypes?region=us-east-1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **instanceTypes** (array) - A list of available instance types.
  - **name** (string) - The name of the instance type.
  - **vcpus** (integer) - The number of vCPUs.
  - **ram** (integer) - The amount of RAM in GB.
  - **hourlyRate** (number) - The hourly cost of the instance type.
  - **storageMonthlyRate** (number) - The monthly cost of storage per GB.
  - **region** (string) - The region where this instance type is available.

#### Response Example
```json
{
  "instanceTypes": [
    {"name": "db.t3.micro", "vcpus": 2, "ram": 1, "hourlyRate": 0.02, "storageMonthlyRate": 0.10, "region": "us-east-1"},
    {"name": "db.t3.medium", "vcpus": 2, "ram": 4, "hourlyRate": 0.08, "storageMonthlyRate": 0.10, "region": "us-east-1"},
    {"name": "db.t3.large", "vcpus": 2, "ram": 8, "hourlyRate": 0.16, "storageMonthlyRate": 0.10, "region": "us-east-1"}
  ]
}
```
```

```APIDOC
## GET /organizations/{organizationID}/images

### Description
Lists available PostgreSQL images for a given region.

### Method
GET

### Endpoint
/organizations/{organizationID}/images

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.

#### Query Parameters
- **region** (string) - Required - The ID of the region to list images for.

### Request Example
```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/images?region=us-east-1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **images** (array) - A list of available PostgreSQL images.
  - **name** (string) - The name of the image (e.g., "postgres:16").
  - **majorVersion** (string) - The major version of PostgreSQL.
  - **fullVersion** (string) - The full version of PostgreSQL.
  - **region** (array of strings) - The regions where this image is available.

#### Response Example
```json
{
  "images": [
    {"name": "postgres:16", "majorVersion": "16", "fullVersion": "16.2", "region": ["us-east-1", "eu-west-1"]},
    {"name": "postgres:15", "majorVersion": "15", "fullVersion": "15.6", "region": ["us-east-1", "eu-west-1"]}
  ]
}
```
```

--------------------------------

### Create PostgreSQL Cluster Request

Source: https://context7.com/xataio/xata/llms.txt

Specifies the parameters required to create a new PostgreSQL cluster, including its ID, configuration, parent ID for branching, organization and project IDs, backup configuration, and data source options like snapshots or restores.

```protobuf
// Example: Create cluster request
message CreatePostgresClusterRequest {
  string id = 1;                              // Branch ID
  ClusterConfiguration configuration = 2;     // Cluster settings
  optional string parent_id = 3;              // For CoW branching
  string organization_id = 4;
  string project_id = 5;
  BackupConfiguration backup_configuration = 6;
  oneof data_source {
    ClusterSnapshot cluster_snapshot = 7;     // CoW from snapshot
    ContinuousBackup continuous_backup = 8;   // PITR restore
    BaseBackup base_backup = 9;               // Full backup restore
  }
  optional bool use_pool = 10;                // Adopt from cluster pool
}
```

--------------------------------

### Update Project Configuration

Source: https://context7.com/xataio/xata/llms.txt

Modify the configuration of an existing project, such as renaming it or adjusting scale-to-zero settings.

```bash
curl -X PATCH "https://api.xata.io/organizations/{organizationID}/projects/{projectID}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "renamed-project",
    "configuration": {
      "scaleToZero": {
        "childBranches": {"enabled": true, "inactivityPeriodMinutes": 20}
      }
    }
  }'
```

--------------------------------

### Manage Organization Invitations via cURL

Source: https://context7.com/xataio/xata/llms.txt

Commands to send, list, resend, and delete user invitations for an organization.

```bash
curl -X POST "https://api.xata.io/organizations/{organizationID}/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "newmember@example.com"}'
```

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/invitations?status=pending" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl -X POST "https://api.xata.io/organizations/{organizationID}/invitations/{invitationID}/resend" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl -X DELETE "https://api.xata.io/organizations/{organizationID}/invitations/{invitationID}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Projects API - Create Project

Source: https://context7.com/xataio/xata/llms.txt

Creates a new project container within an organization. Projects hold database branches and their associated resources.

```APIDOC
## POST /organizations/{organizationID}/projects

### Description
Creates a new project container within an organization. Projects hold database branches and their associated resources.

### Method
POST

### Endpoint
/organizations/{organizationID}/projects

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.

#### Request Body
- **name** (string) - Required - The name of the project.
- **configuration** (object) - Optional - Project configuration settings.
  - **scaleToZero** (object) - Optional - Scale-to-zero configuration.
    - **baseBranches** (object) - Optional - Configuration for base branches.
      - **enabled** (boolean) - Optional - Whether scale-to-zero is enabled for base branches.
      - **inactivityPeriodMinutes** (integer) - Optional - Inactivity period in minutes for base branches.
    - **childBranches** (object) - Optional - Configuration for child branches.
      - **enabled** (boolean) - Optional - Whether scale-to-zero is enabled for child branches.
      - **inactivityPeriodMinutes** (integer) - Optional - Inactivity period in minutes for child branches.
  - **ipFiltering** (object) - Optional - IP filtering configuration.
    - **enabled** (boolean) - Optional - Whether IP filtering is enabled.
    - **cidr** (array) - Optional - List of CIDR blocks.
      - **cidr** (string) - Required - The CIDR block.
      - **description** (string) - Optional - Description of the CIDR block.

### Request Example
```json
{
  "name": "my-application",
  "configuration": {
    "scaleToZero": {
      "baseBranches": {
        "enabled": false,
        "inactivityPeriodMinutes": 30
      },
      "childBranches": {
        "enabled": true,
        "inactivityPeriodMinutes": 15
      }
    },
    "ipFiltering": {
      "enabled": true,
      "cidr": [
        {"cidr": "10.0.0.0/8", "description": "Internal network"},
        {"cidr": "192.168.1.0/24", "description": "Office VPN"}
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created project.
- **name** (string) - The name of the project.
- **createdAt** (string) - The timestamp when the project was created.
- **updatedAt** (string) - The timestamp when the project was last updated.
- **configuration** (object) - The configuration of the project.

#### Response Example
```json
{
  "id": "prj_abc123def456",
  "name": "my-application",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "configuration": {}
}
```
```

--------------------------------

### Hibernate a Branch

Source: https://context7.com/xataio/xata/llms.txt

Scales down a branch to zero instances immediately by enabling hibernation. Use this to save costs on inactive branches. Re-enabling requires a separate update.

```bash
# Hibernate a branch (scale to zero immediately)
curl -X PATCH "https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hibernate": true}'
```

--------------------------------

### Branch Custom Resource (Kubernetes)

Source: https://context7.com/xataio/xata/llms.txt

Definition and configuration for a PostgreSQL database branch using Kubernetes Custom Resource.

```APIDOC
## Branch Custom Resource (Kubernetes)

### Description
The Branch CRD is managed by the branch-operator and represents a PostgreSQL database branch with its configuration, backup settings, and scale-to-zero capabilities.

### Kind
Branch

### API Version
xata.io/v1alpha1

### Spec Fields
- **cluster** (object) - Cluster configuration.
  - **name** (string) - The name of the cluster.
  - **image** (string) - The container image for the PostgreSQL instance.
  - **instances** (integer) - The number of PostgreSQL instances.
  - **resources** (object) - Resource requests and limits for the instances.
    - **requests** (object) - Resource requests.
      - **cpu** (string) - CPU request (e.g., "500m").
      - **memory** (string) - Memory request (e.g., "1Gi").
    - **limits** (object) - Resource limits.
      - **cpu** (string) - CPU limit (e.g., "2000m").
      - **memory** (string) - Memory limit (e.g., "4Gi").
  - **storage** (object) - Storage configuration.
    - **size** (string) - The size of the storage (e.g., "100Gi").
    - **storageClass** (string) - The storage class to use.
    - **volumeSnapshotClass** (string) - The volume snapshot class to use.
  - **postgres** (object) - PostgreSQL specific configuration.
    - **parameters** (array of objects) - PostgreSQL parameters.
      - **name** (string) - The name of the parameter.
      - **value** (string) - The value of the parameter.
    - **sharedPreloadLibraries** (array of strings) - Shared preload libraries to load.
  - **scaleToZero** (object) - Scale-to-zero configuration.
    - **enabled** (boolean) - Whether scale-to-zero is enabled.
    - **inactivityPeriodMinutes** (integer) - The inactivity period in minutes before scaling to zero.
  - **hibernation** (string) - Hibernation status (e.g., "Disabled").
  - **affinity** (object) - Node affinity settings.
    - **nodeSelector** (object) - Node selector labels.
      - **node-type** (string) - Example node selector.
- **backup** (object) - Backup configuration.
  - **retention** (string) - Backup retention period (e.g., "7d").
  - **walArchiving** (string) - WAL archiving status (e.g., "Enabled").
  - **scheduledBackup** (object) - Scheduled backup configuration.
    - **schedule** (string) - Cron schedule for backups (e.g., "0 0 2 * * *").
- **pooler** (object) - Connection pooler (PgBouncer) configuration.
  - **instances** (integer) - The number of pooler instances.
  - **mode** (string) - The pooler mode (e.g., "transaction").
  - **maxClientConn** (string) - Maximum client connections.
  - **defaultPoolSize** (string) - Default pool size.
- **inheritedMetadata** (object) - Metadata inherited by child resources.
  - **labels** (object) - Labels to apply.
    - **environment** (string) - Example label.
    - **team** (string) - Example label.

### Example
```yaml
apiVersion: xata.io/v1alpha1
kind: Branch
metadata:
  name: production-main
spec:
  cluster:
    name: production-main-cluster
    image: "ghcr.io/xataio/postgres:16"
    instances: 2
    resources:
      requests:
        cpu: "500m"
        memory: "1Gi"
      limits:
        cpu: "2000m"
        memory: "4Gi"
    storage:
      size: "100Gi"
      storageClass: "fast-ssd"
      volumeSnapshotClass: "csi-snapshotter"
    postgres:
      parameters:
        - name: max_connections
          value: "200"
        - name: shared_buffers
          value: "512MB"
      sharedPreloadLibraries:
        - pg_stat_statements
        - auto_explain
    scaleToZero:
      enabled: false
      inactivityPeriodMinutes: 30
    hibernation: Disabled
    affinity:
      nodeSelector:
        node-type: database

  backup:
    retention: "7d"
    walArchiving: Enabled
    scheduledBackup:
      schedule: "0 0 2 * * *"  # Daily at 2 AM

  pooler:
    instances: 2
    mode: transaction
    maxClientConn: "500"
    defaultPoolSize: "50"

  inheritedMetadata:
    labels:
      environment: production
      team: platform
```
```

--------------------------------

### gRPC CreatePostgresCluster

Source: https://context7.com/xataio/xata/llms.txt

Creates a new PostgreSQL cluster with specified configuration, including support for snapshots, continuous backups, and base backups.

```APIDOC
## gRPC CreatePostgresCluster

### Description
Creates a new PostgreSQL cluster instance within the specified organization and project.

### Method
gRPC

### Endpoint
ClustersService.CreatePostgresCluster

### Request Body
- **id** (string) - Required - Branch ID
- **configuration** (ClusterConfiguration) - Required - Cluster settings
- **parent_id** (string) - Optional - For CoW branching
- **organization_id** (string) - Required - Organization identifier
- **project_id** (string) - Required - Project identifier
- **backup_configuration** (BackupConfiguration) - Required - Backup settings
- **data_source** (oneof) - Optional - ClusterSnapshot, ContinuousBackup, or BaseBackup
- **use_pool** (bool) - Optional - Adopt from cluster pool

### Request Example
{
  "id": "branch-123",
  "organization_id": "org-456",
  "project_id": "proj-789",
  "configuration": {
    "num_instances": 1,
    "storage_size": 10
  }
}
```

--------------------------------

### POST /organizations/{organizationID}/api-keys

Source: https://context7.com/xataio/xata/llms.txt

Creates and manages API keys with granular scopes for authentication.

```APIDOC
## POST /organizations/{organizationID}/api-keys

### Description
Creates a new API key with specific scopes, project restrictions, and branch restrictions.

### Parameters
#### Path Parameters
- **organizationID** (string) - Required - The ID of the organization.

#### Request Body
- **name** (string) - Required - Name of the API key.
- **expiry** (string) - Optional - ISO 8601 timestamp for key expiration.
- **scopes** (array) - Optional - List of permission scopes.
- **projects** (array) - Optional - List of project IDs the key is restricted to.
- **branches** (array) - Optional - List of branch IDs the key is restricted to.

### Response
#### Success Response (200)
- **key** (object) - The created API key details including the token.
```

--------------------------------

### Manage API Keys via cURL

Source: https://context7.com/xataio/xata/llms.txt

Operations for listing, deleting, and creating API keys within a Xata organization.

```bash
curl -X GET "https://api.xata.io/organizations/{organizationID}/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash
curl -X DELETE "https://api.xata.io/organizations/{organizationID}/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["key_abc123", "key_def456"]}'
```

```bash
curl -X POST "https://api.xata.io/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Personal Development Key", "expiry": null}'
```

--------------------------------

### Define Xata Branch with Volume Snapshot

Source: https://context7.com/xataio/xata/llms.txt

Use this YAML configuration to create a child branch from a parent using a volume snapshot for Copy-on-Write functionality.

```yaml
apiVersion: xata.io/v1alpha1
kind: Branch
metadata:
  name: feature-user-auth
spec:
  restore:
    type: VolumeSnapshot
    name: production-main-snapshot
  cluster:
    name: feature-user-auth-cluster
    image: "ghcr.io/xataio/postgres:16"
    instances: 1
    storage:
      size: "100Gi"
    scaleToZero:
      enabled: true
      inactivityPeriodMinutes: 15
    hibernation: Disabled
```

--------------------------------

### Execute SQL Query via HTTP Serverless

Source: https://context7.com/xataio/xata/llms.txt

Use this endpoint to execute SQL queries through Xata's serverless driver. Supports parameterized queries and batch operations within transactions. Ensure the 'Connection-String' header is correctly formatted.

```bash
curl -X POST "https://br_main_abc123.us-east-1.xata.tech/sql" \
  -H "Connection-String: postgres://user:pass@br_main_abc123.us-east-1.xata.tech/mydb" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT id, name, email FROM users WHERE created_at > $1 LIMIT 10",
    "params": ["2024-01-01"]
  }'
```

```bash
curl -X POST "https://br_main_abc123.us-east-1.xata.tech/sql" \
  -H "Connection-String: postgres://user:pass@host/db" \
  -H "Array-Mode: true" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT id, name FROM users"}'
```

```bash
curl -X POST "https://br_main_abc123.us-east-1.xata.tech/sql" \
  -H "Connection-String: postgres://user:pass@host/db" \
  -H "Batch-Isolation-Level: Serializable" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"query": "INSERT INTO orders (user_id, total) VALUES ($1, $2) RETURNING id", "params": [1, 99.99]},
      {"query": "UPDATE users SET order_count = order_count + 1 WHERE id = $1", "params": [1]},
      {"query": "SELECT * FROM orders WHERE user_id = $1 ORDER BY created_at DESC LIMIT 5", "params": [1]}
    ]
  }'
```

--------------------------------

### List Organizations

Source: https://context7.com/xataio/xata/llms.txt

Retrieve a list of all organizations the authenticated user belongs to. Requires an API key in the 'Authorization' header.

```bash
curl -X GET "https://api.xata.io/organizations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### POST /sql

Source: https://context7.com/xataio/xata/llms.txt

Executes SQL queries via HTTP. Supports single queries, batch operations within transactions, and parameterized queries.

```APIDOC
## POST /sql

### Description
Executes SQL queries against a Xata database via the serverless driver. Supports single queries, batch transactions, and parameterized inputs.

### Method
POST

### Endpoint
https://{branch_id}.{region}.xata.tech/sql

### Request Body
- **query** (string) - Optional - A single SQL query string.
- **params** (array) - Optional - Parameters for the single query.
- **queries** (array) - Optional - A list of query objects for batch execution.

### Response
#### Success Response (200)
- **command** (string) - The SQL command type.
- **rowCount** (integer) - Number of rows affected or returned.
- **rows** (array) - The result set rows.
- **results** (array) - Results for batch operations.
```

--------------------------------

### POST /organizations/{orgID}/projects/{projectID}/branches/{branchID}/metrics

Source: https://context7.com/xataio/xata/llms.txt

Retrieves performance metrics for a branch including CPU, memory, disk usage, connections, and I/O statistics.

```APIDOC
## POST /organizations/{orgID}/projects/{projectID}/branches/{branchID}/metrics

### Description
Retrieves performance metrics for a branch including CPU, memory, disk usage, connections, and I/O statistics.

### Method
POST

### Endpoint
https://api.xata.io/organizations/{orgID}/projects/{projectID}/branches/{branchID}/metrics

### Request Body
- **start** (string) - Required - Start timestamp
- **end** (string) - Required - End timestamp
- **metric** (string) - Required - Metric type (e.g., cpu)
- **instances** (array) - Required - List of instance IDs
- **aggregations** (array) - Required - List of aggregations (e.g., avg, max)
```

--------------------------------

### Delete a Project

Source: https://context7.com/xataio/xata/llms.txt

Remove a project and all its associated branches and data. Use with extreme caution.

```bash
curl -X DELETE "https://api.xata.io/organizations/{organizationID}/projects/{projectID}" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Define gRPC Clusters Service

Source: https://context7.com/xataio/xata/llms.txt

Defines the available RPC methods for managing PostgreSQL clusters, including creation, description, update, deletion, credential retrieval, and IP filtering.

```protobuf
// Create a new PostgreSQL cluster
service ClustersService {
  rpc CreatePostgresCluster(CreatePostgresClusterRequest) returns (CreatePostgresClusterResponse);
  rpc DescribePostgresCluster(DescribePostgresClusterRequest) returns (DescribePostgresClusterResponse);
  rpc UpdatePostgresCluster(UpdatePostgresClusterRequest) returns (UpdatePostgresClusterResponse);
  rpc DeletePostgresCluster(DeletePostgresClusterRequest) returns (DeletePostgresClusterResponse);
  rpc GetPostgresClusterCredentials(GetPostgresClusterCredentialsRequest) returns (GetPostgresClusterCredentialsResponse);
  rpc SetBranchIPFiltering(SetBranchIPFilteringRequest) returns (SetBranchIPFilteringResponse);
}
```