Database Table by Name

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

This endpoint provides a way to mutate a specific table on a database.

Expected Parameters
NameDescriptionInRequiredSchema
db_branch_nameThe DBBranchName matches the pattern `{db_name}:{branch_name}`. pathstring
table_nameThe Table namepathstring

Create Table

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

Creates a new table with the given name. Returns 422 if a table with the same name already exists.

Possible Responses
Status CodeDescriptionExample Response/Type Definition
201Created
{
  "branchName": "mydb_main",
  "tableName": "mytable"
}
400Bad Request
type CreateTable = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type CreateTable = {
    id?: string;
    message: string;
};
422Example response
type CreateTable = {
    id?: string;
    message: string;
};
5XXUnexpected Error

Delete Table

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

Deletes the table with the given name.

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

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

Update Table

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

Update table. Currently there is only one update operation supported: renaming the table by providing a new name.

In the example below, we rename a table from “users” to “people”:

// PATCH /db/test:main/tables/users

{
  "name": "people"
}
Request Body Type Definition
type UpdateTable = {
    /*
     * @minLength 1
     */
    name: string;
};
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200Schema migration response with ID and migration status.
type UpdateTable = {
    /*
     * @minLength 1
     */
    migrationID: string;
    parentMigrationID: string;
    status: MigrationStatus;
};

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