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 Example

{
  "branchName": "main",
  "region": "us-east-1",
  "metadata": {
    "repository": "github.com/my/repository",
    "branch": "github repository",
    "stage": "testing",
    "labels": [
      "development"
    ]
  }
}

Request Body Type Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
/**
 * @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;

Status Code	Description	Example Response/Type Definition
201	Created	`{ "databaseName": "New Database", "status": "completed" }`
400	Bad Request	`type CreateDatabase = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
422	Example response	`type CreateDatabase = { id?: string; message: string; };`
423	Example response	`type CreateDatabase = { id?: string; message: string; };`
5XX	Unexpected 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.

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

Get Database Metadata

GET

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

Retrieve metadata of the given database

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

1
2
3
4
5
6
7
8
type UpdateDatabaseMetadata = {
    ui?: {
        /*
         * @minLength 1
         */
        color?: string;
    };
};

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