Database Branch by Name

https://{your-workspace-slug}.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
NameDescriptionInRequiredSchema
db_branch_nameThe DBBranchName matches the pattern `{db_name}:{branch_name}`. pathstring

Get Branch Schema and Metadata

GET  https://{your-workspace-slug}.xata.sh/db/{db_branch_name}/
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200OK
type GetBranchDetails = {
    databaseName: DBName;
    branchName: BranchName;
    createdAt: DateTime;
    id: string;
    version: number;
    lastMigrationID: string;
    metadata?: BranchMetadata;
    startedFrom?: StartedFromMetadata;
    schema: Schema;
};

/**
 * @pattern [a-zA-Z0-9_\-~]+
 */
type DBName = string;

/**
 * @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[];
};

/**
 * @pattern [a-zA-Z0-9_\-~]+
 */
type TableName = string;

type Column = {
    name: string;
    type: "bool" | "int" | "float" | "string" | "text" | "email" | "multiple" | "link" | "object" | "datetime";
    link?: {
        table: string;
    };
    columns?: Column[];
};

type RevLink = {
    linkID: string;
    table: string;
};
400Bad Request
type GetBranchDetails = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type GetBranchDetails = {
    id?: string;
    message: string;
};
5XXUnexpected Error

Create Database Branch

PUT  https://{your-workspace-slug}.xata.sh/db/{db_branch_name}/
Expected Parameters
NameDescriptionInRequiredSchema
fromName of source branch to branch the new schema fromquery-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[];
};

/**
 * @pattern [a-zA-Z0-9_\-~]+
 */
type BranchName = string;
Possible Responses
Status CodeDescriptionExample Response/Type Definition
201Created
{
  "databaseName": "mydatabase",
  "branchName": "mybranch"
}
400Bad Request
type CreateBranch = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type CreateBranch = {
    id?: string;
    message: string;
};
5XXUnexpected Error

Delete Database Branch

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

Delete the branch in the database and all its resources

Possible Responses
Status CodeDescriptionExample Response/Type Definition
204No Content
400Bad Request
type DeleteBranch = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type DeleteBranch = {
    id?: string;
    message: string;
};
5XXUnexpected Error