Database Branch by Name

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name

This path allows interacting with a given database branch, referenced by parameter db_branch_name, which is expected in the format database_name:branch_name.

Expected parameters

Name	Description	In	Required	Schema
`db_branch_name`	The DBBranchName matches the pattern `{db_name}:{branch_name}`.	path	✅	string

Get Branch Schema and Metadata

GET

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name

Responses

type GetBranchDetails = {
    databaseName: DBName;
    branchName: BranchName;
    createdAt: DateTime;
    id: string;
    version: number;
    lastMigrationID: string;
    metadata?: BranchMetadata;
    startedFrom?: StartedFromMetadata;
    schema: Schema;
};
 
/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_\-~]+
 */
type DBName = string;
 
/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_\-~]+
 */
type BranchName = string;
 
/**
 * @format date-time
 */
type DateTime = string;
 
/**
 * @example {"repository":"github.com/my/repository","branch":"feature-login","stage":"testing","labels":["epic-100"]}
 */
type BranchMetadata = {
    /**
     * @minLength 1
     */
    repository?: string;
    branch?: BranchName;
    /**
     * @minLength 1
     */
    stage?: string;
    labels?: string[];
};
 
type StartedFromMetadata = {
    branchName: BranchName;
    dbBranchID: string;
    migrationID: string;
};
 
type Schema = {
    tables: Table[];
    tablesOrder?: string[];
};
 
type Table = {
    id?: string;
    name: TableName;
    columns: Column[];
    revLinks?: RevLink[];
};
 
/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_\-~]+
 */
type TableName = string;
 
type Column = {
    name: string;
    type: "bool" | "int" | "float" | "string" | "text" | "email" | "multiple" | "link" | "object" | "datetime" | "vector" | "file[]" | "file" | "json";
    link?: ColumnLink;
    vector?: ColumnVector;
    file?: ColumnFile;
    ["file[]"]?: ColumnFile;
    notNull?: boolean;
    defaultValue?: string;
    unique?: boolean;
    columns?: Column[];
};
 
type RevLink = {
    table: string;
    column: string;
};
 
type ColumnLink = {
    table: string;
};
 
type ColumnVector = {
    /**
     * @maximum 10000
     * @minimum 2
     */
    dimension: number;
};
 
type ColumnFile = {
    defaultPublicAccess?: boolean;
};

type GetBranchDetails = {
    id?: string;
    message: string;
};

{
    "message": "invalid API key"
}

type GetBranchDetails = {
    id?: string;
    message: string;
};

type GetBranchDetails = void;

type GetBranchDetails = void;

Create Database Branch

PUT

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name

Expected parameters

Name	Description	In	Required	Schema
`from`	Name of source branch to branch the new schema from	query	-	string

Request Body Type Definition

type CreateBranch = {
    /**
     * Select the branch to fork from. Defaults to 'main'
     */
    from?: string;
    metadata?: BranchMetadata;
};
 
/**
 * @example {"repository":"github.com/my/repository","branch":"feature-login","stage":"testing","labels":["epic-100"]}
 */
type BranchMetadata = {
    /**
     * @minLength 1
     */
    repository?: string;
    branch?: BranchName;
    /**
     * @minLength 1
     */
    stage?: string;
    labels?: string[];
};
 
/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_\-~]+
 */
type BranchName = string;

Responses

{
    "databaseName": "mydatabase",
    "branchName": "mybranch",
    "status": "completed"
}

type CreateBranch = {
    id?: string;
    message: string;
};

{
    "message": "invalid API key"
}

type CreateBranch = {
    id?: string;
    message: string;
};

type CreateBranch = {
    id?: string;
    message: string;
};

type CreateBranch = void;

type CreateBranch = void;

Delete Database Branch

DELETE

https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name

Delete the branch in the database and all its resources

Responses

type DeleteBranch = {
    status: MigrationStatus;
};
 
type MigrationStatus = "completed" | "pending" | "failed";

type DeleteBranch = {
    id?: string;
    message: string;
};

{
    "message": "invalid API key"
}

type DeleteBranch = {
    id?: string;
    message: string;
};

type DeleteBranch = {
    id?: string;
    message: string;
};

type DeleteBranch = void;

type DeleteBranch = void;