Table Record

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
`record_id`	The Record name	path	✅	string
`columns`	Column filters	query	-	array

Get Record by ID

GET

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

Retrieve record by ID

Status Code	Description	Example Response/Type Definition
200	Table Record Reponse	/** * Xata Table Record Metadata / type GetRecord = RecordMeta & { [key: string]: any; }; /* * Xata Table Record Metadata / type RecordMeta = { id: RecordID; xata: { / * The record's version. Can be used for optimistic concurrency control. / version: number; / * The record's table name. APIs that return records from multiple tables will set this field accordingly. / table?: string; / * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search. / highlight?: { [key: string]: string[] \| { [key: string]: any; }; }; / * The record's relevancy score. This is returned by the search APIs. / score?: number; / * Encoding/Decoding errors / warnings?: string[]; }; }; /* * @pattern [a-zA-Z0-9_-~:]+ */ type RecordID = string;
400	Bad Request	`type GetRecord = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type GetRecord = { id?: string; message: string; };`
5XX	Unexpected Error

Insert Record With ID

PUT

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

By default, IDs are auto-generated when data is insterted into Xata. Sending a request to this endpoint allows us to insert a record with a pre-existing ID, bypassing the default automatic ID generation.

Expected Parameters

Name	Description	In	Required	Schema
`createOnly`		query	-	boolean
`ifVersion`		query	-	integer

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
41
42
43
44
45
46
type InsertRecordWithID = Record<string, any>;

/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};

/**
 * Xata Table Record Metadata
 */
type RecordMeta = {
    id: RecordID;
    xata: {
        /*
         * The record's version. Can be used for optimistic concurrency control.
         */
        version: number;
        /*
         * The record's table name. APIs that return records from multiple tables will set this field accordingly.
         */
        table?: string;
        /*
         * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search.
         */
        highlight?: {
            [key: string]: string[] | {
                [key: string]: any;
            };
        };
        /*
         * The record's relevancy score. This is returned by the search APIs.
         */
        score?: number;
        /*
         * Encoding/Decoding errors
         */
        warnings?: string[];
    };
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;

Status Code	Description	Example Response/Type Definition
200	Record ID and version	type InsertRecordWithID = Record \| { id: string; xata: { version: number; }; }; /** * Xata Table Record Metadata / type Record = RecordMeta & { [key: string]: any; }; /* * Xata Table Record Metadata / type RecordMeta = { id: RecordID; xata: { / * The record's version. Can be used for optimistic concurrency control. / version: number; / * The record's table name. APIs that return records from multiple tables will set this field accordingly. / table?: string; / * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search. / highlight?: { [key: string]: string[] \| { [key: string]: any; }; }; / * The record's relevancy score. This is returned by the search APIs. / score?: number; / * Encoding/Decoding errors / warnings?: string[]; }; }; /* * @pattern [a-zA-Z0-9_-~:]+ */ type RecordID = string;
201	Record ID and version	type InsertRecordWithID = Record \| { id: string; xata: { version: number; }; }; /** * Xata Table Record Metadata / type Record = RecordMeta & { [key: string]: any; }; /* * Xata Table Record Metadata / type RecordMeta = { id: RecordID; xata: { / * The record's version. Can be used for optimistic concurrency control. / version: number; / * The record's table name. APIs that return records from multiple tables will set this field accordingly. / table?: string; / * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search. / highlight?: { [key: string]: string[] \| { [key: string]: any; }; }; / * The record's relevancy score. This is returned by the search APIs. / score?: number; / * Encoding/Decoding errors / warnings?: string[]; }; }; /* * @pattern [a-zA-Z0-9_-~:]+ */ type RecordID = string;
400	Bad Request	`type InsertRecordWithID = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type InsertRecordWithID = { id?: string; message: string; };`
422	Example response	`type InsertRecordWithID = { id?: string; message: string; };`
5XX	Unexpected Error

Update Record With ID

PATCH

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

Expected Parameters

Name	Description	In	Required	Schema
`ifVersion`		query	-	integer

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
41
42
43
44
45
46
type UpdateRecordWithID = Record<string, any>;

/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};

/**
 * Xata Table Record Metadata
 */
type RecordMeta = {
    id: RecordID;
    xata: {
        /*
         * The record's version. Can be used for optimistic concurrency control.
         */
        version: number;
        /*
         * The record's table name. APIs that return records from multiple tables will set this field accordingly.
         */
        table?: string;
        /*
         * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search.
         */
        highlight?: {
            [key: string]: string[] | {
                [key: string]: any;
            };
        };
        /*
         * The record's relevancy score. This is returned by the search APIs.
         */
        score?: number;
        /*
         * Encoding/Decoding errors
         */
        warnings?: string[];
    };
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;

Status Code	Description	Example Response/Type Definition
200	Record ID and version	type UpdateRecordWithID = Record \| { id: string; xata: { version: number; }; }; /** * Xata Table Record Metadata / type Record = RecordMeta & { [key: string]: any; }; /* * Xata Table Record Metadata / type RecordMeta = { id: RecordID; xata: { / * The record's version. Can be used for optimistic concurrency control. / version: number; / * The record's table name. APIs that return records from multiple tables will set this field accordingly. / table?: string; / * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search. / highlight?: { [key: string]: string[] \| { [key: string]: any; }; }; / * The record's relevancy score. This is returned by the search APIs. / score?: number; / * Encoding/Decoding errors / warnings?: string[]; }; }; /* * @pattern [a-zA-Z0-9_-~:]+ */ type RecordID = string;
400	Bad Request	`type UpdateRecordWithID = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type UpdateRecordWithID = { id?: string; message: string; };`
422	Example response	`type UpdateRecordWithID = { id?: string; message: string; };`
5XX	Unexpected Error

Upsert Record With ID

POST

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

Expected Parameters

Name	Description	In	Required	Schema
`ifVersion`		query	-	integer

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
41
42
43
44
45
46
type UpsertRecordWithID = Record<string, any>;

/**
 * Xata Table Record Metadata
 */
type Record = RecordMeta & {
    [key: string]: any;
};

/**
 * Xata Table Record Metadata
 */
type RecordMeta = {
    id: RecordID;
    xata: {
        /*
         * The record's version. Can be used for optimistic concurrency control.
         */
        version: number;
        /*
         * The record's table name. APIs that return records from multiple tables will set this field accordingly.
         */
        table?: string;
        /*
         * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search.
         */
        highlight?: {
            [key: string]: string[] | {
                [key: string]: any;
            };
        };
        /*
         * The record's relevancy score. This is returned by the search APIs.
         */
        score?: number;
        /*
         * Encoding/Decoding errors
         */
        warnings?: string[];
    };
};

/**
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;

Status Code	Description	Example Response/Type Definition
200	Record ID and version	type UpsertRecordWithID = Record \| { id: string; xata: { version: number; }; }; /** * Xata Table Record Metadata / type Record = RecordMeta & { [key: string]: any; }; /* * Xata Table Record Metadata / type RecordMeta = { id: RecordID; xata: { / * The record's version. Can be used for optimistic concurrency control. / version: number; / * The record's table name. APIs that return records from multiple tables will set this field accordingly. / table?: string; / * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search. / highlight?: { [key: string]: string[] \| { [key: string]: any; }; }; / * The record's relevancy score. This is returned by the search APIs. / score?: number; / * Encoding/Decoding errors / warnings?: string[]; }; }; /* * @pattern [a-zA-Z0-9_-~:]+ */ type RecordID = string;
201	Record ID and version	type UpsertRecordWithID = Record \| { id: string; xata: { version: number; }; }; /** * Xata Table Record Metadata / type Record = RecordMeta & { [key: string]: any; }; /* * Xata Table Record Metadata / type RecordMeta = { id: RecordID; xata: { / * The record's version. Can be used for optimistic concurrency control. / version: number; / * The record's table name. APIs that return records from multiple tables will set this field accordingly. / table?: string; / * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search. / highlight?: { [key: string]: string[] \| { [key: string]: any; }; }; / * The record's relevancy score. This is returned by the search APIs. / score?: number; / * Encoding/Decoding errors / warnings?: string[]; }; }; /* * @pattern [a-zA-Z0-9_-~:]+ */ type RecordID = string;
400	Bad Request	`type UpsertRecordWithID = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type UpsertRecordWithID = { id?: string; message: string; };`
422	Example response	`type UpsertRecordWithID = { id?: string; message: string; };`
5XX	Unexpected Error

Delete Record From Table

DELETE

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

Status Code	Description	Example Response/Type Definition
200	Table Record Reponse	/** * Xata Table Record Metadata / type DeleteRecord = RecordMeta & { [key: string]: any; }; /* * Xata Table Record Metadata / type RecordMeta = { id: RecordID; xata: { / * The record's version. Can be used for optimistic concurrency control. / version: number; / * The record's table name. APIs that return records from multiple tables will set this field accordingly. / table?: string; / * Highlights of the record. This is used by the search APIs to indicate which fields and parts of the fields have matched the search. / highlight?: { [key: string]: string[] \| { [key: string]: any; }; }; / * The record's relevancy score. This is returned by the search APIs. / score?: number; / * Encoding/Decoding errors / warnings?: string[]; }; }; /* * @pattern [a-zA-Z0-9_-~:]+ */ type RecordID = string;
204	No Content
400	Bad Request	`type DeleteRecord = { id?: string; message: string; };`
401	Authentication Error	`{ "message": "invalid API key" }`
404	Example response	`type DeleteRecord = { id?: string; message: string; };`
5XX	Unexpected Error