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

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:

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

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

mode values

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

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

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

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"
}

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