Xata

Table Record

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

This endpoint enables mutating a given record in a table, referenced by its ID.

Expected Parameters

NameDescriptionInRequiredSchema
db_branch_nameThe DBBranchName matches the pattern `{db_name}:{branch_name}`. path✅string
table_nameThe Table namepath✅string
record_idThe Record namepath✅string
columnsColumn filtersquery-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 CodeDescriptionExample Response/Type Definition
200Table 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 time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * 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[];
    };
};

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
400Bad Request
type GetRecord = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type GetRecord = {
    id?: string;
    message: string;
};
5XXUnexpected Error
defaultUnexpected 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

NameDescriptionInRequiredSchema
createOnlyquery-boolean
ifVersionquery-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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
type InsertRecordWithID = DataInputRecord;

/**
 * Xata input record
 */
type DataInputRecord = {
    [key: string]: RecordID | string | boolean | number | string[] | number[] | DateTime | ObjectValue | InputFileArray | InputFile | null;
};

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

/**
 * @format date-time
 */
type DateTime = string;

/**
 * Object column value
 */
type ObjectValue = {
    [key: string]: string | boolean | number | string[] | number[] | DateTime | ObjectValue;
};

/**
 * Array of file entries
 * 
 * @maxItems 50
 */
type InputFileArray = InputFileEntry[];

/**
 * Object representing a file
 */
type InputFile = {
    name: FileName;
    mediaType?: MediaType;
    /*
     * Base64 encoded content
     *
     * @maxLength 20971520
     */
    base64Content?: string;
    /*
     * Enable public access to the file
     */
    enablePublicUrl?: boolean;
    /*
     * Time to live for signed URLs
     */
    signedUrlTimeout?: number;
};

/**
 * Object representing a file in an array
 */
type InputFileEntry = {
    id?: FileItemID;
    name?: FileName;
    mediaType?: MediaType;
    /*
     * Base64 encoded content
     *
     * @maxLength 20971520
     */
    base64Content?: string;
    /*
     * Enable public access to the file
     */
    enablePublicUrl?: boolean;
    /*
     * Time to live for signed URLs
     */
    signedUrlTimeout?: number;
};

/**
 * File name
 * 
 * @maxLength 1024
 * @minLength 0
 * @pattern [0-9a-zA-Z!\-_\.\*'\(\)]*
 */
type FileName = string;

/**
 * Media type
 * 
 * @maxLength 255
 * @minLength 3
 * @pattern ^\w+/[-+.\w]+$
 */
type MediaType = string;

/**
 * Unique file identifier
 * 
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type FileItemID = string;
Status CodeDescriptionExample Response/Type Definition
200Record ID and metadata
type InsertRecordWithID = Record | {
    id: string;
    xata: {
        version: number;
        createdAt: string;
        updatedAt: string;
    };
};

/**
 * 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 time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * 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[];
    };
};

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
201Record ID and metadata
type InsertRecordWithID = Record | {
    id: string;
    xata: {
        version: number;
        createdAt: string;
        updatedAt: string;
    };
};

/**
 * 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 time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * 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[];
    };
};

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
400Bad Request
type InsertRecordWithID = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type InsertRecordWithID = {
    id?: string;
    message: string;
};
422Example response
type InsertRecordWithID = {
    id?: string;
    message: string;
};
5XXUnexpected 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

NameDescriptionInRequiredSchema
ifVersionquery-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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
type UpdateRecordWithID = DataInputRecord;

/**
 * Xata input record
 */
type DataInputRecord = {
    [key: string]: RecordID | string | boolean | number | string[] | number[] | DateTime | ObjectValue | InputFileArray | InputFile | null;
};

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

/**
 * @format date-time
 */
type DateTime = string;

/**
 * Object column value
 */
type ObjectValue = {
    [key: string]: string | boolean | number | string[] | number[] | DateTime | ObjectValue;
};

/**
 * Array of file entries
 * 
 * @maxItems 50
 */
type InputFileArray = InputFileEntry[];

/**
 * Object representing a file
 */
type InputFile = {
    name: FileName;
    mediaType?: MediaType;
    /*
     * Base64 encoded content
     *
     * @maxLength 20971520
     */
    base64Content?: string;
    /*
     * Enable public access to the file
     */
    enablePublicUrl?: boolean;
    /*
     * Time to live for signed URLs
     */
    signedUrlTimeout?: number;
};

/**
 * Object representing a file in an array
 */
type InputFileEntry = {
    id?: FileItemID;
    name?: FileName;
    mediaType?: MediaType;
    /*
     * Base64 encoded content
     *
     * @maxLength 20971520
     */
    base64Content?: string;
    /*
     * Enable public access to the file
     */
    enablePublicUrl?: boolean;
    /*
     * Time to live for signed URLs
     */
    signedUrlTimeout?: number;
};

/**
 * File name
 * 
 * @maxLength 1024
 * @minLength 0
 * @pattern [0-9a-zA-Z!\-_\.\*'\(\)]*
 */
type FileName = string;

/**
 * Media type
 * 
 * @maxLength 255
 * @minLength 3
 * @pattern ^\w+/[-+.\w]+$
 */
type MediaType = string;

/**
 * Unique file identifier
 * 
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type FileItemID = string;
Status CodeDescriptionExample Response/Type Definition
200Record ID and metadata
type UpdateRecordWithID = Record | {
    id: string;
    xata: {
        version: number;
        createdAt: string;
        updatedAt: string;
    };
};

/**
 * 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 time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * 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[];
    };
};

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
400Bad Request
type UpdateRecordWithID = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type UpdateRecordWithID = {
    id?: string;
    message: string;
};
422Example response
type UpdateRecordWithID = {
    id?: string;
    message: string;
};
5XXUnexpected 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

NameDescriptionInRequiredSchema
ifVersionquery-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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
type UpsertRecordWithID = DataInputRecord;

/**
 * Xata input record
 */
type DataInputRecord = {
    [key: string]: RecordID | string | boolean | number | string[] | number[] | DateTime | ObjectValue | InputFileArray | InputFile | null;
};

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

/**
 * @format date-time
 */
type DateTime = string;

/**
 * Object column value
 */
type ObjectValue = {
    [key: string]: string | boolean | number | string[] | number[] | DateTime | ObjectValue;
};

/**
 * Array of file entries
 * 
 * @maxItems 50
 */
type InputFileArray = InputFileEntry[];

/**
 * Object representing a file
 */
type InputFile = {
    name: FileName;
    mediaType?: MediaType;
    /*
     * Base64 encoded content
     *
     * @maxLength 20971520
     */
    base64Content?: string;
    /*
     * Enable public access to the file
     */
    enablePublicUrl?: boolean;
    /*
     * Time to live for signed URLs
     */
    signedUrlTimeout?: number;
};

/**
 * Object representing a file in an array
 */
type InputFileEntry = {
    id?: FileItemID;
    name?: FileName;
    mediaType?: MediaType;
    /*
     * Base64 encoded content
     *
     * @maxLength 20971520
     */
    base64Content?: string;
    /*
     * Enable public access to the file
     */
    enablePublicUrl?: boolean;
    /*
     * Time to live for signed URLs
     */
    signedUrlTimeout?: number;
};

/**
 * File name
 * 
 * @maxLength 1024
 * @minLength 0
 * @pattern [0-9a-zA-Z!\-_\.\*'\(\)]*
 */
type FileName = string;

/**
 * Media type
 * 
 * @maxLength 255
 * @minLength 3
 * @pattern ^\w+/[-+.\w]+$
 */
type MediaType = string;

/**
 * Unique file identifier
 * 
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type FileItemID = string;
Status CodeDescriptionExample Response/Type Definition
200Record ID and metadata
type UpsertRecordWithID = Record | {
    id: string;
    xata: {
        version: number;
        createdAt: string;
        updatedAt: string;
    };
};

/**
 * 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 time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * 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[];
    };
};

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
201Record ID and metadata
type UpsertRecordWithID = Record | {
    id: string;
    xata: {
        version: number;
        createdAt: string;
        updatedAt: string;
    };
};

/**
 * 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 time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * 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[];
    };
};

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
400Bad Request
type UpsertRecordWithID = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type UpsertRecordWithID = {
    id?: string;
    message: string;
};
422Example response
type UpsertRecordWithID = {
    id?: string;
    message: string;
};
5XXUnexpected Error

Delete Record From Table

DELETE
https://{your-workspace-slug}.{region}.xata.sh/db/db_branch_name/tables/table_name/data/record_id
Status CodeDescriptionExample Response/Type Definition
200Table 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 time when the record was created.
         */
        createdAt?: string;
        /*
         * The time when the record was last updated.
         */
        updatedAt?: string;
        /*
         * 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[];
    };
};

/**
 * @maxLength 255
 * @minLength 1
 * @pattern [a-zA-Z0-9_-~:]+
 */
type RecordID = string;
204No Content
400Bad Request
type DeleteRecord = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type DeleteRecord = {
    id?: string;
    message: string;
};
5XXUnexpected Error