tabtab

name	tabtab
description	Use TabTab to run AI-powered tasks in a sandboxed multi-agent environment. Supported capabilities: - General agent: open-ended tasks, writing, research, summarisation - Data analysis: upload CSV / Excel files, run analytics, generate insights - Data collection: web scraping and browser automation to collect structured data - Chart generation: produce charts and visualisations from data - Deep research: long-form research with web search and synthesised reports - Database Q&A: natural-language to SQL queries against connected databases - Slide generation: create PowerPoint presentations - Web / HTML generation: produce web pages or UI prototypes Interact via REST API: create tasks, poll status, stream event logs, terminate tasks, and download sandbox output.
metadata	{"category":"integration,automation,api,data-analysis,research,scraping","required_env":"TABTAB_API_KEY","optional_env":"TABTAB_BASE_URL","dependencies":"curl,jq,stat"}

TabTab Skill

Overview

The TabTab OpenPlatform exposes REST endpoints under /open/apis/v1/ that let you drive TabTab's multi-agent platform programmatically. Every request must carry an API Key in the Authorization header.

Authorization: Bearer sk-<32-hex-chars>

The API Key is obtained from the KMS page(https://tabtabai.com/api-key) in TabTab settings and stored as environment variable TABTAB_API_KEY.

---

Configuration — Set environment variables

Recommended: write to scripts/env (persists across sessions, not in shell history)

cat > "$(dirname "$0")/scripts/env" <<'EOF'
TABTAB_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TABTAB_BASE_URL="https://tabtabai.com"   # optional
EOF
chmod 600 "$(dirname "$0")/scripts/env"

All scripts automatically source scripts/env on startup if the file exists — no further setup needed.

Security: chmod 600 ensures only you can read the file. Add scripts/env to .gitignore to prevent accidental commits:

echo "skills/tabtab/scripts/env" >> .gitignore

Alternative: export in shell session (lost on terminal close)

export TABTAB_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export TABTAB_BASE_URL="https://tabtabai.com"  # optional

Warning: Commands typed with the key inline (e.g. export TABTAB_API_KEY="sk-...") are saved to shell history (.bash_history / .zsh_history). Prefer the scripts/env file approach above, or set the key via a password manager / secrets tool that avoids writing to history.

Verify configuration

echo "BASE_URL : ${TABTAB_BASE_URL:-https://tabtabai.com}"
echo "API_KEY  : ${TABTAB_API_KEY:0:8}…"  # print only first 8 chars for safety

# Verify API key is valid before proceeding — stop if this fails
bash scripts/hello.sh

Variable	Required	Description
TABTAB_API_KEY	✅	API Key in sk-… format obtained from KMS page
TABTAB_BASE_URL	❌	Base URL of TabTab instance (default: https://tabtabai.com)

If TABTAB_API_KEY is empty, all scripts will immediately exit with an error.

Required tools

The scripts depend on the following tools — confirm they are installed from trusted packages:

Tool	Purpose
curl	HTTP requests to the API
jq	JSON parsing and transformation
stat	File size check before upload (upload-files.sh)

---

---

Step 0 — Verify connectivity

Check API Key validity before proceeding:

bash scripts/hello.sh

Expected (200):

{
  "message": "Hello from TabTab OpenPlatform!",
  "timestamp": "2026-03-09T10:00:00+00:00",
  "user_id": "<internal-user-id>"
}

If response is 401, the key is missing, revoked, or expired — stop and report error to user.

---

Step 1 — Upload files (optional)

If your task requires file inputs (e.g., analyzing a spreadsheet, processing a PDF, or extracting data from images), upload them first:

Upload multiple files (batch)

FILES_INFO=$(TABTAB_FILES="file1.pdf file2.png data.xlsx" bash scripts/upload-files.sh)
echo "$FILES_INFO"

File restrictions

Restriction	Value
Max file size	50MB per file
Max files per task	20 files
Supported types	PDF, Word (.doc, .docx), Excel (.xls, .xlsx), PowerPoint (.ppt, .pptx), Text (.txt, .md), Images (.jpg, .jpeg, .png, .gif, .webp, .bmp, .svg, .tiff, .tif, .ico), Archives (.zip, .rar, .7z, .tar, .gz)

Note: MIME type validation is lenient. The primary validation is based on file extension. This accommodates variations in MIME type reporting across different browsers and systems.

---

Step 2 — Create a task

Submit a new task and get back a task_id immediately. The task is queued for agent execution; you will poll for its result in the next step.

Create task with files (using scripts)

# First upload files
FILES_INFO=$(TABTAB_FILES="report.pdf chart.png" bash scripts/upload-files.sh)
FILES_JSON=$(echo "$FILES_INFO" | jq -c '.files')

# Then create task with files
TASK_ID=$(TABTAB_MESSAGE="Analyze the attached documents" \
  TABTAB_MODE="data_analysis" \
  TABTAB_FILES="$FILES_JSON" \
  bash scripts/create-task.sh)

Create task without files

TASK_ID=$(TABTAB_MESSAGE="Research quantum computing trends" \
  TABTAB_MODE="deep_research" \
  bash scripts/create-task.sh)

Request fields

Field	Type	Required	Description
message	string	✅	Initial user prompt — task goal
mode	string	✅	Execution strategy (see table below)
run_mode	string	❌	agent (default) or chat
params	object	❌	Extra parameters, e.g. {"output": "report"}
files	array	❌	List of uploaded files (only effective in agent mode)

mode values

Mode	When to use
general	Open-ended tasks, research, writing
data_analysis	CSV / Excel / database analytics
deep_research	Long-form research with web search
data_collect	Structured data scraping / collection
html	Web page / UI generation
ppt	Slide deck generation
charts	Chart / visualisation generation
chat_db	Natural language to SQL
flash	Fast single-step tasks

Expected response (201)

{
  "status": "pending",
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}

---

Step 3 — Poll task status

Poll until status leaves pending / running:

STATUS=$(TABTAB_TASK_ID="$TASK_ID" bash scripts/poll-task.sh)
echo "Final status: $STATUS"

For manual polling:

while true; do
  STATUS=$(TABTAB_TASK_ID="$TASK_ID" bash scripts/get-status.sh)
  echo "status: $STATUS"

  case "$STATUS" in
    completed | failed | cancelled) break ;;
    hitl)
      echo "Task is waiting for human input — check the TabTab UI."
      break
      ;;
  esac

  sleep 5
done

Status lifecycle

pending → running → completed
                  ↘ failed
                  ↘ cancelled
                  ↘ hitl  (waiting for user action in UI)

Response fields

Field	Description
status	Current task status
status_message	Human-readable detail (non-empty on failed)

---

Step 4 — Retrieve event log

Fetch all events for a completed (or still-running) task to inspect what the agent did:

# Get all events — stdout is the saved file path
EVENTS_FILE=$(TABTAB_TASK_ID="$TASK_ID" bash scripts/get-events.sh)
jq '.events[].event_type' "$EVENTS_FILE"

# Custom output path
EVENTS_FILE=$(TABTAB_TASK_ID="$TASK_ID" \
  TABTAB_EVENTS_FILE=/tmp/my-events.json \
  bash scripts/get-events.sh)

# Get incremental events (streaming-style)
LAST_EVENT_ID=""
while true; do
  EVENTS_FILE=$(TABTAB_TASK_ID="$TASK_ID" \
    TABTAB_FROM_EVENT_ID="$LAST_EVENT_ID" \
    bash scripts/get-events.sh)

  # Update cursor — read from the saved file
  NEW_LAST=$(jq -r '.events[-1].event_id // empty' "$EVENTS_FILE")
  [ -n "$NEW_LAST" ] && LAST_EVENT_ID="$NEW_LAST"

  # Stop when task is done
  STATUS=$(TABTAB_TASK_ID="$TASK_ID" bash scripts/get-status.sh | jq -r '.status')
  case "$STATUS" in completed | failed | cancelled) break ;; esac

  sleep 3
done

Key event types

event_type	Meaning
user_input	Original user prompt
agent_state_change	Agent phase transition (planning → executing → done)
tool_call_item	A complete tool call with input + output
message_output_item	Agent text output / final answer
think_output_item	Agent internal reasoning (if thinking mode enabled)
token_usage	LLM token consumption for one step
task_final_usage	Aggregate token + tool usage for the whole task
hitl_operation	Human-in-the-loop pause/resume event

---

Step 5 — Download sandbox output

Download the working directory of a task as a ZIP file:

# Download entire sandbox
OUT=$(TABTAB_TASK_ID="$TASK_ID" bash scripts/download.sh)
echo "Saved to: $OUT"

# Download a specific sub-directory only
OUT=$(TABTAB_TASK_ID="$TASK_ID" TABTAB_DIR="output" \
  TABTAB_OUT="/workspace/result.zip" \
  bash scripts/download.sh)
echo "Saved to: $OUT"

The response is a Content-Type: application/zip streaming file.

---

Step 6 — Terminate a running task (optional)

Send a stop signal to cancel a running task:

TABTAB_TASK_ID="$TASK_ID" bash scripts/terminate-task.sh

The signal is asynchronous — poll status until it becomes cancelled.

---

Helper scripts

The skill ships ready-to-use shell scripts under scripts/. Use these scripts for most operations — they handle authentication, JSON parsing, and error handling automatically.

Quick reference

Script	Purpose
hello.sh	Test API connectivity
upload-files.sh	Upload multiple files in batch
create-task.sh	Create a new task
list-tasks.sh	List all tasks with pagination
get-status.sh	Get current status of a task
get-events.sh	Get event log for a task
poll-task.sh	Poll until task finishes (blocking)
download.sh	Download sandbox output as ZIP
terminate-task.sh	Cancel a running task

---

Complete end-to-end example (reference)

This example shows the complete flow using both scripts and direct curl commands (for reference). For actual usage, prefer the scripts shown above.

# ── Config ─────────────────────────────────────────────
# Set these in your shell session before running (never store secrets in a file):
# export TABTAB_API_KEY="sk-..."
# export TABTAB_BASE_URL="https://tabtabai.com"  # optional
BASE="${TABTAB_BASE_URL:-https://tabtabai.com}"
KEY="$TABTAB_API_KEY"

# ── 0. Verify ──────────────────────────────────────────
bash scripts/hello.sh

# ── 1. Upload files ───────────────────────────────────
FILES_INFO=$(TABTAB_FILES="report.pdf chart.png" bash scripts/upload-files.sh)
FILES_JSON=$(echo "$FILES_INFO" | jq -c '.files')

# ── 2. Create task with files ───────────────────────
TASK_ID=$(TABTAB_MESSAGE="Analyze the sales data in attachments and generate trend report" \
  TABTAB_MODE="data_analysis" \
  TABTAB_FILES="$FILES_JSON" \
  bash scripts/create-task.sh)
echo "Created task: $TASK_ID"

# ── 3. Poll ────────────────────────────────────────────
STATUS=$(TABTAB_TASK_ID="$TASK_ID" bash scripts/poll-task.sh)

# ── 4. Download output ─────────────────────────────────
[ "$STATUS" = "completed" ] \
  && TABTAB_TASK_ID="$TASK_ID" bash scripts/download.sh > /dev/null 2>&1 \
  && echo "Download complete"

---

Error handling

All endpoints return a consistent error body on failure:

{
  "code": 401,
  "err_code": "30001",
  "message": "unauthorized. 30001",
  "status": "error"
}

HTTP	err_code	Meaning
400	400	Invalid file type or size exceeds limit
401	30000	API Key missing or invalid format
401	30001	API Key revoked
401	30002	API Key expired
403	403	Task belongs to a different user
404	404	Task not found
500	50000	Internal server error — retry or contact support

Always check the HTTP status code and err_code before proceeding. Do not retry 401/403/404 errors automatically — they require user action.

---

Best Practices

1. Always use scripts: They handle authentication, JSON parsing, and error handling automatically
2. Verify connectivity first: Run bash scripts/hello.sh after setting credentials — if it fails, stop and fix the key before proceeding
3. Export env vars in your shell session: Set TABTAB_API_KEY (and optionally TABTAB_BASE_URL) via export before using any script. Never store secrets in plain-text files inside the skill directory.
4. Check response codes: Scripts return proper exit codes; check $? after each call
5. Capture stderr for progress: Scripts write progress to stderr, output to stdout for capture
6. Use poll-task.sh for blocking: It waits until completion, simpler than manual polling loops