Table Records

Insert, query, update, and delete Table records. The external REST route is /v1/tables/:tableId/records; legacy /api/.../rows and MCP row tool names remain supported for compatibility. Column names are fuzzy-matched on insert — typos are auto-corrected within 2 character edits (Levenshtein distance). Every record automatically gets system fields: _ht_id, _ht_created_at, _ht_updated_at, _ht_status, _ht_error.

Insert Records

POST/v1/tables/:tableId/recordshypertab_insert_rows

Insert up to 10,000 records per call. Column names are fuzzy-matched — if you pass companey instead of company, it auto-corrects and notes the correction in the response. If smart columns have auto-run enabled, they trigger automatically after insert.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`records`required	`object[]`	Array of record objects with column: value pairs. Max 10,000 records per call.

Fuzzy Matching

Column names within Levenshtein distance of 2 are auto-corrected. Unrecognized columns beyond that threshold are ignored and reported in the response.

System columns (_ht_id, _ht_created_at, etc.) are auto-generated. Do not include them in your record objects.

{
  "tool": "hypertab_insert_rows",
  "arguments": {
    "table": "leads",
    "rows": [
      { "company": "Acme Corp", "website": "https://acme.com", "size": 500 },
      { "company": "Globex Inc", "website": "https://globex.com", "size": 1200 },
      { "company": "Initech", "website": "https://initech.com", "size": 80 }
    ]
  }
}

Query Records

GET/v1/tables/:tableId/recordshypertab_query_rows

Query records with filters, sorting, and cursor/offset pagination. Returns a maximum of 1000 records per page (MAX_ROWS_PER_QUERY), defaulting to 25. The Use pagination to retrieve larger result sets; one response never represents an unbounded export.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`where`	`object`	Filter conditions: { column: { operator: value } }. See Filter Syntax.
`order_by`	`object`	Sort specification: { column: "asc" \| "desc" }
`limit`	`integer`default: 25	Records per page (max 1000)
`offset`	`integer`default: 0	Number of records to skip for pagination
`after_id`	`string`	Cursor: return records after this _ht_id. Prefer over offset for deep pagination.
`include_total`	`boolean`	Include the total matching-record count in the response.
`columns`	`string[]`	Specific columns to return. Omit to return all columns.

See Filter Syntax for all available operators including eq, neq, gt, gte, lt, lte, contains, starts_with, in, between, is_null, and more.

AI Tools

Use selective filters and cursor pagination for large reads. Use the export flow when the goal is to retrieve the complete Table rather than an interactive page.

{
  "tool": "hypertab_query_rows",
  "arguments": {
    "table": "leads",
    "where": {
      "size": { "gte": 500 },
      "industry": { "eq": "SaaS" }
    },
    "order_by": { "size": "desc" },
    "columns": ["company", "website", "size", "industry"],
    "limit": 50,
    "offset": 0
  }
}

Get Record

GET/v1/tables/:tableId/records/:recordIdhypertab_get_row

Get a single record by its _ht_id. Returns all columns including system fields and smart column cell states.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`recordId`required	`string`	The _ht_id of the record to retrieve
`columns`	`string[]`	Specific columns to return. Omit to return all columns.

Use this after inserting or updating a record to verify the result, or to inspect smart column cell states for a specific record.

{
  "tool": "hypertab_get_row",
  "arguments": {
    "table": "leads",
    "row_id": "d54e84ca-1a2b-4c3d-8e9f-1234567890ab"
  }
}

Update Records

PATCH/v1/tables/:tableId/recordshypertab_update_rows

Bulk update records by filter or specific record IDs. Provide at least one of where or record_ids to target records. The set object specifies column values to update.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`set`required	`object`	Column values to set: { column: value }
`where`	`object`	Filter to match records: { column: { operator: value } }
`record_ids`	`string[]`	Specific record IDs (_ht_id values) to update

At least one of where or record_ids is required. Omitting both will return an error — there is no "update all records" shortcut.

System columns (_ht_updated_at, _ht_status) are updated automatically. You cannot set them directly.

{
  "tool": "hypertab_update_rows",
  "arguments": {
    "table": "leads",
    "where": { "status": { "eq": "prospect" } },
    "set": { "status": "qualified", "score": 85 }
  }
}

Delete Records

DELETE/v1/tables/:tableId/recordshypertab_delete_rows

Soft-delete records by filter or specific record IDs. Records are marked with _ht_status = 'deleted' and excluded from future queries. Requires confirm: true when deleting more than 10 records as a safety measure.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`where`	`object`	Filter to match records for deletion
`record_ids`	`string[]`	Specific record IDs (_ht_id values) to delete
`confirm`	`boolean`	Required true if deleting more than 10 records

Safety Check

If your filter or record_ids would affect more than 10 records, you must pass confirm: true. Without it, the operation returns an error showing the count of records that would be affected.

This is a soft-delete. Records are not physically removed immediately. They are automatically excluded from all queries. Undo a delete (or a dedupe) with hypertab_restore_rows, passing the affected record_ids or a deleted_after timestamp.

{
  "tool": "hypertab_delete_rows",
  "arguments": {
    "table": "leads",
    "where": { "status": { "eq": "spam" } },
    "confirm": true
  }
}

Upsert Records

POST/v1/tables/:tableId/recordshypertab_upsert_rows

Insert or update records based on a unique column. If a record with the same value in the unique_on column already exists, it is updated with the new values. Otherwise, a new record is inserted. Max 10,000 records per call. Over REST, this shares the POST /v1/tables/:tableId/records endpoint — including unique_on in the body switches it to upsert mode.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`records`required	`object[]`	Array of record objects to upsert. Max 10,000.
`unique_on`required	`string`	Column name to check for uniqueness (e.g. "email", "domain")

When to Use Upsert

Use upsert when you have data that may partially overlap with existing records. Common use cases: syncing CRM data, enrichment results, or webhook payloads where duplicates are possible.

AI Tools

Prefer upsert over query-then-update workflows. It avoids race conditions and is a single API call instead of two.

{
  "tool": "hypertab_upsert_rows",
  "arguments": {
    "table": "leads",
    "unique_on": "email",
    "rows": [
      { "email": "[email protected]", "score": 85, "status": "qualified" },
      { "email": "[email protected]", "score": 72, "status": "prospect" },
      { "email": "[email protected]", "company": "Initech", "score": 60 }
    ]
  }
}

Count Records

GET/v1/tables/:tableId/counthypertab_count_rows

Count records matching a filter. Significantly faster than querying all records when you only need the count. Supports the same filter syntax as query_rows.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`where`	`object`	Filter conditions: { column: { operator: value } }. Omit for total record count.

AI Tools

Use count_rows before a bulk operation to check how many records will be affected. This avoids surprises with update_rows or delete_rows.

See Filter Syntax for all available operators.

{
  "tool": "hypertab_count_rows",
  "arguments": {
    "table": "leads",
    "where": { "status": { "eq": "qualified" } }
  }
}

Tables

Smart Columns