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
NameDescriptionInRequiredSchema
workspace_idWorkspace IDpathstring
db_nameThe Database Namepathstring

Create Database

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

Create Database with identifier name

Request Body Example
{
  "example-1": {
    "branchName": "main",
    "metadata": {
      "repository": "github.com/my/repository",
      "branch": "github repository",
      "stage": "testing",
      "labels": [
        "development"
      ]
    }
  }
}
Request Body Type Definition
/**
 * @example {"example-1":{"branchName":"main","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[];
};

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

Delete Database

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

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

Possible Responses
Status CodeDescriptionExample Response/Type Definition
200OK
type DeleteDatabase = {
    status: MigrationStatus;
};

type MigrationStatus = "completed" | "pending" | "failed";
400Bad Request
type DeleteDatabase = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type DeleteDatabase = {
    id?: string;
    message: string;
};
5XXUnexpected Error

Get Database Metadata

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

Retrieve metadata of the given database

Possible Responses
Status CodeDescriptionExample Response/Type Definition
200OK
/**
 * 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;
400Bad Request
type GetDatabaseMetadata = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type GetDatabaseMetadata = {
    id?: string;
    message: string;
};
5XXUnexpected Error

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;
    };
};
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200OK
/**
 * 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;
400Bad Request
type UpdateDatabaseMetadata = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type UpdateDatabaseMetadata = {
    id?: string;
    message: string;
};
5XXUnexpected Error