Tables

Tables are the core data structure in Hypertab. Each table has columns (static or smart) and records. Every record automatically gets five system columns: _ht_id, _ht_created_at, _ht_updated_at, _ht_status, _ht_error.

Naming Rules

Table and column names must match /^[a-z][a-z0-9_]*$/ — lowercase letters, digits, and underscores only, starting with a letter. Names cannot start with _ht_ (reserved for system columns).

Table Workspace

The web table view includes persistent server-side search, saved views, a table-wide auto-run toggle for smart columns, sticky two-line column headers, and inline filter chips. Each column header also exposes a direct menu for sorting, clearing sort, filtering that column, pinning, hiding, and smart-column run actions.

Custom Views

Tables can also have persisted presentation views: board, gallery, calendar, form, and timeline. These views are created from the table bottom bar or through MCP with hypertab_create_view, then customized with field mappings and brand styling in the view studio.

List Tables

GET/v1/tableshypertab_list_tables

Returns all tables in the workspace with record counts, column counts, and descriptions. Soft-deleted tables are excluded.

No parameters required.

AI Tools

Call this first to discover available tables before querying records or modifying schemas.

{
  "tool": "hypertab_list_tables"
}

Create Table

POST/v1/tableshypertab_create_table

Create a new Table inside an existing Project with one or more columns. The five system columns are added automatically. You can mix static data columns and smart columns in the same call.

Parameter	Type	Description
`project_id`required	`string`	ID of the Project that will own the new Table.
`name`required	`string`	Table name. Must match /^[a-z][a-z0-9_]*$/. Cannot start with _ht_. Max 64 chars.
`description`	`string`	Human-readable description. Max 500 chars.
`columns`required	`Column[]`	Array of column definitions. Each entry has name (string), type (string), and optional config (object).

Column Types

Available types: text, number, boolean, email, url, phone, datetime, json, select, multi_select, relation, currency, image_url. For select and multi_select, pass a config object with an options array.

Each column definition requires name and type. The optional config object holds type-specific settings like select options or relation targets.

Table names must be unique within a workspace. Creating a table with a duplicate name returns a TABLE_ALREADY_EXISTS error.

{
  "tool": "hypertab_create_table",
  "arguments": {
	"project_id": "pg_project_123",
    "name": "companies",
    "description": "Target companies for outreach",
    "columns": [
      { "name": "name", "type": "text" },
      { "name": "website", "type": "url" },
      { "name": "employees", "type": "number" },
      { "name": "annual_revenue", "type": "currency" },
      { "name": "industry", "type": "select", "config": { "options": ["SaaS", "Finance", "Healthcare"] } },
      { "name": "tags", "type": "multi_select", "config": { "options": ["enterprise", "mid-market", "startup"] } }
    ]
  }
}

Exact retry replay

A successful create returns 201. Reusing the same stable Idempotency-Key with the same payload replays the original result and exact Table identity without creating a duplicate. Reusing that key with a different payload returns IDEMPOTENCY_KEY_REUSED.

Get Table Schema

GET/v1/tables/:tableIdhypertab_get_table_schema

Returns the full schema of a table including all columns, their types, kinds (static or smart), configs, and positions. Use this to understand a table's structure before inserting or querying records.

Parameter	Type	Description
`table`required	`string`	Table name or ID.

AI Tools

Always read the schema before querying or updating records. Column names are case-sensitive and must match exactly. Smart columns include their kind, config, and auto_run settings.

The response includes both user-defined columns and system columns. System columns are prefixed with _ht_ and cannot be modified.

{
  "tool": "hypertab_get_table_schema",
  "arguments": {
    "table": "companies"
  }
}

Add Column

POST/v1/tables/:tableId/columnshypertab_add_column

Add a new static data column to an existing table. For smart columns (HTTP, formula, integration, etc.), use hypertab_add_smart_column instead.

Parameter	Type	Description
`table`required	`string`	Table name or ID.
`name`required	`string`	Column name. Must match /^[a-z][a-z0-9_]*$/. Cannot start with _ht_. Max 64 chars.
`type`required	`string`	One of: text, number, boolean, email, url, phone, datetime, json, select, multi_select, relation, currency, image_url.
`config`	`object`	Type-specific config. For select/multi_select: { options: ["a", "b"] }. For relation: { table: "other_table" }.

Column Types Reference

text — free-form string
number — numeric value
boolean — true/false
email — validated email address
url — validated URL string
phone — phone number
datetime — ISO 8601 timestamp
json — arbitrary JSON object
select — single choice from options (config: { options: [...] })
multi_select — multiple choices from options (config: { options: [...] })
relation — link to another table (config: { table: "other_table" })
currency — monetary value
image_url — image URL string

New columns are appended to the end of the table by default. Existing records get null for the new column.

Column names must be unique within a table. Adding a column with a duplicate name returns a COLUMN_ALREADY_EXISTS error.

{
  "tool": "hypertab_add_column",
  "arguments": {
    "table": "companies",
    "name": "status",
    "type": "select",
    "config": {
      "options": ["Active", "Churned", "Prospect"]
    }
  }
}

Update Table

PATCH/v1/tables/:tableIdhypertab_update_table

Rename a table or update its description. At least one of new_name or description must be provided.

Parameter	Type	Description
`table`required	`string`	Current table name or ID.
`new_name`	`string`	New table name. Must match /^[a-z][a-z0-9_]*$/. Max 64 chars.
`description`	`string \| null`	New description. Pass null to clear.

Renaming a table updates all internal references. Existing webhooks and smart columns that reference this table continue to work because they use the table ID internally.

Pass description: null to clear the description entirely.

{
  "tool": "hypertab_update_table",
  "arguments": {
    "table": "companies",
    "new_name": "target_accounts",
    "description": "Enterprise target accounts for Q2"
  }
}

Update Column

PATCH/v1/tables/:tableId/columns/:columnIdhypertab_update_column

Rename a column, change its type, update its config (e.g. select options), or reorder it. All fields are optional — provide only the ones you want to change.

Parameter	Type	Description
`table`required	`string`	Table name or ID.
`column`required	`string`	Current column name.
`new_name`	`string`	New column name. Must match /^[a-z][a-z0-9_]*$/. Max 64 chars.
`new_type`	`string`	New column type. One of: text, number, boolean, email, url, phone, datetime, json, select, multi_select, relation, currency, image_url.
`config`	`object \| null`	Updated type config (e.g. select options). Pass null to clear.
`position`	`integer`	New display position (0-indexed).

Type Changes

Changing a column's type may cause data loss. For example, converting from json to number will set non-numeric values to null. Review your data before changing types.

Use position to reorder columns in the table display. Position is 0-indexed. Other columns shift automatically.

{
  "tool": "hypertab_update_column",
  "arguments": {
    "table": "companies",
    "column": "employees",
    "new_name": "employee_count"
  }
}

Delete Column

DELETE/v1/tables/:tableId/columns/:columnIdhypertab_delete_column

Permanently remove a column from a table. All data in the column is lost. This action cannot be undone. Requires confirm: true as a safety guard.

Parameter	Type	Description
`table`required	`string`	Table name or ID.
`column`required	`string`	Column name to delete.
`confirm`required	`boolean`	Must be true to confirm deletion.

Destructive Action

This permanently deletes the column and all its data. There is no recovery. System columns (_ht_id, _ht_created_at, etc.) cannot be deleted.

AI Tools

Always confirm with the user before deleting a column. If confirm is missing or false, the request is rejected with a CONFIRMATION_REQUIRED error.

{
  "tool": "hypertab_delete_column",
  "arguments": {
    "table": "companies",
    "column": "old_notes",
    "confirm": true
  }
}

Delete Table

DELETE/v1/tables/:tableIdhypertab_delete_table

Soft-delete a table. The table and all its data are hidden but recoverable for 30 days using hypertab_restore_table. After 30 days, the table is permanently purged. Requires confirm: true.

Parameter	Type	Description
`table`required	`string`	Table name or ID.
`confirm`required	`boolean`	Must be true to confirm deletion.

Soft Delete

Deleted tables are excluded from hypertab_list_tables and cannot be queried. Associated webhooks, sources, and smart column runs are paused. Restore within 30 days to recover everything.

AI Tools

Always confirm with the user before deleting a table. Without confirm: true, the request is rejected.

{
  "tool": "hypertab_delete_table",
  "arguments": {
    "table": "old_leads",
    "confirm": true
  }
}

Restore Table

POST/v1/tables/:tableId/restorehypertab_restore_table

Restore a soft-deleted Table and its stored records and columns within the 30-day recovery window. Inspect dependent Sources, webhooks, and workflow runs after restoration; they may remain paused or require repair.

Parameter	Type	Description
`table`required	`string`	Deleted table name or ID.

30-Day Window

Tables can only be restored within 30 days of deletion. After that, the table and all associated data are permanently purged. Check recoverable_until in the delete response for the exact deadline.

If a new table with the same name was created after deletion, the restore will fail with a TABLE_ALREADY_EXISTS error. Rename or delete the conflicting table first.

{
  "tool": "hypertab_restore_table",
  "arguments": {
    "table": "old_leads"
  }
}

Describe Column

GET/v1/tables/:tableId/columns/:columnId/describehypertab_describe_column

Get data statistics for a column: null count, distinct values, min/max values, and top value distribution. Useful for understanding data quality and distribution before building filters or scoring logic.

Parameter	Type	Description
`table`required	`string`	Table name or ID.
`column`required	`string`	Column name.

When to Use

Use this before writing filter or scoring logic to understand the data distribution. For select/multi_select columns, the top values show the most common choices. For number columns, you get min, max, average, and percentiles.

AI Tools

Call this on key columns before building queries. Knowing the min/max range and null count helps you write accurate filters and avoid empty results.

{
  "tool": "hypertab_describe_column",
  "arguments": {
    "table": "companies",
    "column": "employees"
  }
}

Projects

Table Records