Authentication

All API requests require an API key. Keys start with ht_sk_ and are passed as a Bearer token.

REST API

Include your API key in the Authorization header with every request. The base URL is https://api.hypertab.ai/v1. If a key can access multiple workspaces, send X-Hypertab-Workspace with the workspace slug or id.

curl https://api.hypertab.ai/v1/tables \
  -H "Authorization: Bearer ht_sk_YOUR_KEY" \
  -H "X-Hypertab-Workspace: growth-ops"

Local bridge wrapper

After MCP install, scaffold a wrapper, mint a client-bound bridge token, and run the local doctor when a local agent should stream durable progress, upload artifacts, poll commands safely, and report results into Activity.

Wrapper init

npx @hypertabai/mcp bridge wrapper init --type node --out .hypertab/bridge-wrapper.mjs
printf 'Hypertab admin API key: ' >&2; read -rs HYPERTAB_API_KEY; printf '\n' >&2; export HYPERTAB_API_KEY
npx @hypertabai/mcp bridge token create --client-name "$(hostname)-codex" --client-type codex --expires-in-days 30 --json
printf 'Bridge token: ' >&2; read -rs HYPERTAB_API_KEY; printf '\n' >&2; export HYPERTAB_API_KEY
npx @hypertabai/mcp bridge wrapper doctor --path .hypertab/bridge-wrapper.mjs --json
HYPERTAB_BRIDGE_CLIENT_NAME="$(hostname)-codex" HYPERTAB_BRIDGE_CLIENT_TYPE=codex node .hypertab/bridge-wrapper.mjs "Report local bridge health"

MCP Connection

The MCP endpoint uses the same Bearer token. MCP clients connect via Streamable HTTP transport at /mcp. The recommended install path is the one-command installer. It writes the correct MCP config and installs the native Hypertab skill for Claude Code or Codex.

Raw JSON or TOML is still supported for hand editing, but npx @hypertabai/mcp install handles every client's config shape and skill location correctly. Run it without a key in the command, then enter the key at the hidden terminal prompt. The skill file itself is available at app.hypertab.ai/skill.md.

AI Tools

After connecting, read hypertab://guide for operating instructions and hypertab://tables to see your workspace state.

Scoped Keys

API keys can be limited to observe, execute, operate, page:build (legacy scope name for Project creation), bridge, bridge:client, endpoint:manage, artifact:write, or admin capabilities (or the wildcard *). A SCOPE_DENIED response means the key is working but lacks that specific capability.

npx @hypertabai/mcp install

npx @hypertabai/mcp install --client claude-code --scope project

Raw MCP config (reference)

If you prefer to hand-edit, this is what the installer writes. Drop it into .mcp.json in your project root for Claude Code, or into ~/.claude.json under themcpServers key for user-scope install. Cursor uses ~/.cursor/mcp.json, Windsurf uses ~/.codeium/windsurf/mcp_config.json with a serverUrl key instead of url.

.mcp.json (Claude Code)

{
  "mcpServers": {
    "hypertab": {
      "type": "http",
      "url": "https://api.hypertab.ai/mcp",
      "headers": {
        "Authorization": "Bearer ht_sk_YOUR_KEY"
      }
    }
  }
}

WebSocket

Real-time updates use short-lived, one-use tickets. Exchange your credential over HTTPS first; never put an API key or session token in a WebSocket URL.

WebSocket

const response = await fetch('https://api.hypertab.ai/ws/tickets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ht_sk_YOUR_KEY',
    'X-Hypertab-Workspace': 'YOUR_WORKSPACE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ target: 'table', table_id: 'TABLE_ID' })
})
if (!response.ok) throw new Error('Could not issue realtime ticket')
const { data } = await response.json()

// data.ticket expires in <=60s and can be used only once for this Table.
const ws = new WebSocket(
  'wss://api.hypertab.ai/ws/TABLE_ID?ticket=' + encodeURIComponent(data.ticket)
)

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log(data.type, data.payload)
}

Response Format

Every API response follows the same envelope. Success responses include optionalmeta andhints fields.

Success

{
  "success": true,
  "data": { ... },
  "meta": {
    "table": "leads",
    "operation": "query_rows",
    "rows_affected": 25,
    "duration_ms": 12
  },
  "hints": [
    "More records available. Next: offset=25"
  ]
}

Error

{
  "success": false,
  "error": {
    "code": "TABLE_NOT_FOUND",
    "message": "Table 'laeds' not found. Did you mean 'leads'?",
    "suggestion": "Call hypertab_list_tables to see available tables."
  }
}

Introduction

Projects