Single Database

https://api.xata.io/workspaces/workspace_id/dbs/db_name

Given a parameter db_name, this path allows interacting with a specific database on Xata. Below are a number of operations that can be performed on a given database.

Expected parameters

Name	Description	In	Required	Schema
`workspace_id`	Workspace ID	path	✅	string
`db_name`	The Database Name	path	✅	string

Create Database

PUT

https://api.xata.io/workspaces/workspace_id/dbs/db_name

Create Database with identifier name

Request Body Type Definition

/**
 * @example {"branchName":"main","region":"us-east-1","metadata":{"repository":"github.com/my/repository","branch":"github repository","stage":"testing","labels":["development"]}}
 */
type CreateDatabase = {
    /**
     * @minLength 1
     */
    branchName?: string;
    /**
     * @minLength 1
     */
    region: string;
    ui?: {
        color?: 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": "New Database",
    "status": "completed"
}

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

{
    "message": "invalid API key"
}

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

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

type CreateDatabase = void;

Delete Database

DELETE

https://api.xata.io/workspaces/workspace_id/dbs/db_name

Delete a database and all of its branches and tables permanently.

Responses

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

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

{
    "message": "invalid API key"
}

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

type DeleteDatabase = void;

Get Database Metadata

GET

https://api.xata.io/workspaces/workspace_id/dbs/db_name

Retrieve metadata of the given database

Responses

/**
 * Metadata of databases
 */
type GetDatabaseMetadata = {
    /**
     * The machine-readable name of a database
     */
    name: string;
    /**
     * Region where this database is hosted
     */
    region: string;
    /**
     * The time this database was created
     */
    createdAt: DateTime;
    /**
     * Metadata about the database for display in Xata user interfaces
     */
    ui?: {
        /**
         * The user-selected color for this database across interfaces
         */
        color?: string;
    };
};
 
/**
 * @format date-time
 */
type DateTime = string;

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

{
    "message": "invalid API key"
}

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

type GetDatabaseMetadata = void;

Update Database Metadata

PATCH

https://api.xata.io/workspaces/workspace_id/dbs/db_name

Update the color of the selected database

Request Body Type Definition

type UpdateDatabaseMetadata = {
    ui?: {
        /**
         * @minLength 1
         */
        color?: string;
    };
};

Responses

/**
 * Metadata of databases
 */
type UpdateDatabaseMetadata = {
    /**
     * The machine-readable name of a database
     */
    name: string;
    /**
     * Region where this database is hosted
     */
    region: string;
    /**
     * The time this database was created
     */
    createdAt: DateTime;
    /**
     * Metadata about the database for display in Xata user interfaces
     */
    ui?: {
        /**
         * The user-selected color for this database across interfaces
         */
        color?: string;
    };
};
 
/**
 * @format date-time
 */
type DateTime = string;

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

{
    "message": "invalid API key"
}

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

type UpdateDatabaseMetadata = void;