Table Columns

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

This endpoint allows working with a table's columns.

Expected Parameters

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

List Table Columns

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

Retrieves the list of table columns and their definition. This endpoint returns the column list with object columns being reported with their full dot-separated path (flattened).

Status CodeDescriptionExample Response/Type Definition
200OK
{
  "columns": [
    {
      "name": "name",
      "type": "string"
    },
    {
      "name": "email",
      "type": "email"
    },
    {
      "name": "settings.plan",
      "type": "string"
    },
    {
      "name": "settings.dark",
      "type": "bool"
    }
  ]
}
400Bad Request
type GetTableColumns = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type GetTableColumns = {
    id?: string;
    message: string;
};
5XXUnexpected Error

Create New Column

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

Adds a new column to the table. The body of the request should contain the column definition. In the column definition, the 'name' field should contain the full path separated by dots. If the parent objects do not exists, they will be automatically created. For example, passing "name": "address.city" will auto-create the address object if it doesn't exist.

Request Body Example
{
  "name": "columnName",
  "type": "string"
}

Request Body Type Definition

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
/**
 * @example {"name":"columnName","type":"string"}
 */
type AddTableColumn = Column;

type Column = {
    name: string;
    type: "bool" | "int" | "float" | "string" | "text" | "email" | "multiple" | "link" | "object" | "datetime";
    link?: ColumnLink;
    notNull?: boolean;
    defaultValue?: string;
    unique?: boolean;
    columns?: Column[];
};

type ColumnLink = {
    table: string;
};
Status CodeDescriptionExample Response/Type Definition
200Schema migration response with ID and migration status.
type AddTableColumn = {
    /*
     * @minLength 1
     */
    migrationID: string;
    parentMigrationID: string;
    status: MigrationStatus;
};

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