TabTab Skill

Overview

The TabTab OpenPlatform exposes REST endpoints under

/open/apis/v1/

Authorization

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

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

TABTAB_API_KEY

sk-…

TABTAB_BASE_URL

https://tabtabai.com

If

TABTAB_API_KEY

Required tools

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

curl

jq

stat

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

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

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

message

mode

run_mode

agent

chat

params

{"output": "report"}

files

agent

mode

values

general

data_analysis

deep_research

data_collect

html

ppt

charts

chat_db

flash

Expected response (201)

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

Step 3 — Poll task status

Poll until

status

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

status

status_message

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

user_input

agent_state_change

tool_call_item

message_output_item

think_output_item

token_usage

task_final_usage

hitl_operation

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

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

cancelled

Helper scripts

The skill ships ready-to-use shell scripts under

scripts/

Quick reference

hello.sh

upload-files.sh

create-task.sh

list-tasks.sh

get-status.sh

get-events.sh

poll-task.sh

download.sh

terminate-task.sh

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

err_code

400

400

401

30000

401

30001

401

30002

403

403

404

404

500

50000

Always check the HTTP status code and

err_code

401

403

404

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