Rows

Insert, query, update, and delete rows. Column names are fuzzy-matched on insert, so typos are auto-corrected within 2 character edits (Levenshtein distance). Every row automatically gets system columns: _ht_id, _ht_created_at, _ht_updated_at, _ht_status, _ht_error.

Insert Rows

POST/api/tables/:tableId/rowshypertab_insert_rows

Insert up to 10,000 rows 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
`rows`required	`object[]`	Array of row objects with column: value pairs. Max 10,000 rows 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 row 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 Rows

GET/api/tables/:tableId/rowshypertab_query_rows

Query rows with filters, sorting, and pagination. Returns a maximum of 100 rows per page via MCP. The REST API supports limit=0 to return all matching rows without pagination.

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	Rows per page (1-100 via MCP, 0 for all via REST)
`offset`	`integer`default: 0	Number of rows to skip for pagination
`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 Agents

Don't loop query_rows to scan all data, use filters and sorting instead. Via the REST API, pass limit=0 to get all matching rows in a single call (not available through MCP).

{
  "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 Row

GET/api/tables/:tableId/rows/:rowIdhypertab_get_row

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

Parameter	Type	Description
`table`required	`string`	Table name or ID
`row_id`required	`string`	The _ht_id of the row to retrieve

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

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

Update Rows

PATCH/api/tables/:tableId/rowshypertab_update_rows

Bulk update rows by filter or specific row IDs. Provide at least one of where or row_ids to target rows. 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 rows: { column: { operator: value } }
`row_ids`	`string[]`	Specific row IDs to update

At least one of where or row_ids is required. Omitting both will return an error, there is no "update all rows" 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 Rows

DELETE/api/tables/:tableId/rowshypertab_delete_rows

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

Parameter	Type	Description
`table`required	`string`	Table name or ID
`where`	`object`	Filter to match rows for deletion
`row_ids`	`string[]`	Specific row IDs to delete
`confirm`	`boolean`	Required true if deleting more than 10 rows

Safety Check

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

This is a soft-delete. Rows are not physically removed immediately. They are automatically excluded from all queries and can be restored within 30 days.

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

Upsert Rows

POST/api/tables/:tableId/rows/upserthypertab_upsert_rows

Insert or update rows based on a unique column. If a row with the same value in the unique_on column already exists, it is updated with the new values. Otherwise, a new row is inserted. Max 10,000 rows per call.

Parameter	Type	Description
`table`required	`string`	Table name or ID
`rows`required	`object[]`	Array of row 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 rows. Common use cases: syncing CRM data, enrichment results, or webhook payloads where duplicates are possible.

AI Agents

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 Rows

GET/api/tables/:tableId/rows/counthypertab_count_rows

Count rows matching a filter. Significantly faster than querying all rows 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 row count.

AI Agents

Use count_rows before a bulk operation to check how many rows 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