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

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

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.

Status Code	Description	Example Response/Type Definition
201	Created	`{ "branchName": "mydb_main", "tableName": "mytable", "status": "completed" }`
204	No Content
400	Bad Request	`type CreateTable = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type CreateTable = { id?: string; message: string; };`
422	Example response	`type CreateTable = { id?: string; message: string; };`
5XX	Unexpected Error
default	Unexpected Error

DELETE

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

Deletes the table with the given name.

Status Code	Description	Example Response/Type Definition
200	OK	`type DeleteTable = { status: MigrationStatus; }; type MigrationStatus = "completed" \| "pending" \| "failed";`
400	Bad Request	`type DeleteTable = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Not Found
5XX	Unexpected Error
default	Unexpected Error

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”:

1
2
3
4
5
// PATCH /db/test:main/tables/users

{
  "name": "people"
}

1
2
3
4
5
6
type UpdateTable = {
    /*
     * @minLength 1
     */
    name: string;
};

Status Code	Description	Example Response/Type Definition
200	Schema migration response with ID and migration status.	`type UpdateTable = { /* * @minLength 1 */ migrationID: string; parentMigrationID: string; status: MigrationStatus; }; type MigrationStatus = "completed" \| "pending" \| "failed";`
400	Bad Request	`type UpdateTable = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type UpdateTable = { id?: string; message: string; };`
422	Example response	`type UpdateTable = { id?: string; message: string; };`
5XX	Unexpected Error
default	Unexpected Error