Table Record

https://{your-workspace-slug}.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}`. pathstring
table_nameThe Table namepathstring
record_idThe Record namepathstring
columnsColumn filtersquery-array

Insert Record With ID

PUT  https://{your-workspace-slug}.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
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;
Possible Responses
Status CodeDescriptionExample Response/Type Definition
201Record 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;
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}.xata.sh/db/{db_branch_name}/tables/{table_name}/data/{record_id}/
Expected Parameters
NameDescriptionInRequiredSchema
ifVersionquery-integer
Request Body Type Definition
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;
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200Record 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;
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}.xata.sh/db/{db_branch_name}/tables/{table_name}/data/{record_id}/
Expected Parameters
NameDescriptionInRequiredSchema
ifVersionquery-integer
Request Body Type Definition
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;
Possible Responses
Status CodeDescriptionExample Response/Type Definition
200Record 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;
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}.xata.sh/db/{db_branch_name}/tables/{table_name}/data/{record_id}/
Possible Responses
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 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;
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

Get Record by ID

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

Retrieve record by ID

Possible Responses
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 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;
400Bad Request
type GetRecord = {
    id?: string;
    message: string;
};
401Authentication Error
{
  "message": "invalid API key"
}
404Example response
type GetRecord = {
    id?: string;
    message: string;
};
5XXUnexpected Error