aitable-api

Skills

by apitable

Description

Use AITable.ai REST API via curl to manage online spreadsheet data. ALWAYS use this skill when users mention AITable, aitable.ai, aitable, vika, or any of these patterns: - IDs starting with "dst" (datasheet), "spc" (space), "fld" (field), "rec" (record), "viw" (view) - Online collaborative tables/spreadsheets with API operations - Batch import/export data to online tables - Read/create/update/delete records via API - Upload attachments to datasheets - Search datasheets or spaces, list workspaces - Member fields, team management in online tables This skill provides complete curl command examples for AITable REST API. Use it even if the user just mentions "aitable" casually or wants to automate any aitable operations.

AITable.ai API Skill

Interact with AITable.ai via curl commands. No scripts needed - just direct API calls.

Setup

Before making API calls, ensure environment variables are set:

bash

# Set default host if not already set
[ -z "$AITABLE_HOST" ] && export AITABLE_HOST="https://aitable.ai"

# API token is required (get from User Center > Developer Token)
# export AITABLE_TOKEN="uskXXXXXXXXXXXXX"

Run the first line before any curl commands to ensure AITABLE_HOST has the default value.

Quick Reference

Operation	Endpoint	Method
Get records	`/fusion/v1/datasheets/{dstId}/records`	GET
Create records	`/fusion/v1/datasheets/{dstId}/records`	POST
Update records	`/fusion/v1/datasheets/{dstId}/records`	PATCH
Delete records	`/fusion/v1/datasheets/{dstId}/records?recordIds=`	DELETE
Get fields	`/fusion/v1/datasheets/{dstId}/fields`	GET
Create field	`/fusion/v1/spaces/{spcId}/datasheets/{dstId}/fields`	POST
Delete field	`/fusion/v1/spaces/{spcId}/datasheets/{dstId}/fields/{fldId}`	DELETE
Get views	`/fusion/v1/datasheets/{dstId}/views`	GET
Create datasheet	`/fusion/v1/spaces/{spcId}/datasheets`	POST
Upload attachment	`/fusion/v1/datasheets/{dstId}/attachments`	POST
Get spaces	`/fusion/v1/spaces`	GET
Get nodes	`/fusion/v1/spaces/{spcId}/nodes`	GET
Search nodes	`/fusion/v2/spaces/{spcId}/nodes?type=`	GET
Get node detail	`/fusion/v1/spaces/{spcId}/nodes/{nodeId}`	GET

Basic Examples

bash

# Get all records
curl -X GET "$AITABLE_HOST/fusion/v1/datasheets/dstXXX/records" \
  -H "Authorization: Bearer $AITABLE_TOKEN"

# Create records
curl -X POST "$AITABLE_HOST/fusion/v1/datasheets/dstXXX/records" \
  -H "Authorization: Bearer $AITABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"fields":{"Title":"New Task","Status":"Todo"}}]}'

# Update records
curl -X PATCH "$AITABLE_HOST/fusion/v1/datasheets/dstXXX/records" \
  -H "Authorization: Bearer $AITABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"recordId":"recXXX","fields":{"Status":"Done"}}]}'

# Delete records
curl -X DELETE "$AITABLE_HOST/fusion/v1/datasheets/dstXXX/records?recordIds=recXXX&recordIds=recYYY" \
  -H "Authorization: Bearer $AITABLE_TOKEN"

# Upload attachment
curl -X POST "$AITABLE_HOST/fusion/v1/datasheets/dstXXX/attachments" \
  -H "Authorization: Bearer $AITABLE_TOKEN" \
  -F "file=@/path/to/image.png"

# Get spaces list
curl -X GET "$AITABLE_HOST/fusion/v1/spaces" \
  -H "Authorization: Bearer $AITABLE_TOKEN"

# Search datasheets by name
curl -X GET "$AITABLE_HOST/fusion/v2/spaces/spcXXX/nodes?type=Datasheet&query=keyword" \
  -H "Authorization: Bearer $AITABLE_TOKEN"

Response Format

All responses:

json

{"success": true, "code": 200, "message": "SUCCESS", "data": {...}}

Important: cellFormat Parameter for Reading Records

When user wants to read/query records and does NOT specify cellFormat in their request, ASK them to choose:

"Which cell format do you prefer for the response?

string - Human-friendly format, all values converted to strings, dates formatted. Best for viewing data or exporting to CSV.

json - Structured format (default), preserves original types. Best for script processing or multi-step automation.

Use string for simple data viewing; use json for programmatic processing."

Usage:

bash

# Human-readable format (string)
curl -X GET "$AITABLE_HOST/fusion/v1/datasheets/dstXXX/records?cellFormat=string" \
  -H "Authorization: Bearer $AITABLE_TOKEN"

# Structured format for scripts (json, default)
curl -X GET "$AITABLE_HOST/fusion/v1/datasheets/dstXXX/records?cellFormat=json" \
  -H "Authorization: Bearer $AITABLE_TOKEN"

When to skip asking:

User mentions "human readable", "export CSV", "view data", "display" → use string
User mentions "script", "automation", "pipeline", "multi-step", "parse" → use json
Complex multi-step operations or chained commands → use json

Detailed Documentation

For complete parameter details and examples, read the reference files:

Reference	When to read
`references/records.md`	Record CRUD with filtering, sorting, pagination
`references/fields.md`	Field types, create/delete fields
`references/views.md`	Get view list
`references/datasheets.md`	Create new datasheets
`references/attachments.md`	Upload files and use in records
`references/spaces-nodes.md`	Workspaces, folders, search
`references/members-teams.md`	User and team management
`references/field-types.md`	All field value formats

Tips

Use fieldKey=id for stability (field IDs don't change when renamed)
Max 10 records per create/update request
URL-encode filterByFormula values
Upload attachment first, then use its token in record fields