Airtable Web Port

Purpose

This is the Harbor reference integration for the Airtable Web API.

Use it when:

• building Airtable actions in Harbor
• extending the Dock / Hub Airtable entry
• teaching Codex or OpenClaw how to map a record-table API into Harbor Ports and Harbor Actions without turning Harbor into a generic database proxy

Harbor Port worksheet

Product

• Product: Airtable Web API
• Publisher slug: airtable
• Publisher name: Airtable
• Category: Data
• Tags: airtable, database, records, tables, productivity

Safe Harbor Port metadata

• Kind: http_api
• Label: Airtable Web API
• Description: Airtable Web API connection managed locally through Harbor.
• Base URL: https://api.airtable.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Airtable is a good Harbor fit when we keep table access explicit through path parameters and keep writes reviewable.

Good Harbor Airtable actions:

• stable GET routes for table listing and single-record lookup
• one explicit POST route for record creation
• Action Model input.path, input.query, and input.body envelopes instead of freeform URL editing
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for the bounded create request body
• resultMode: "json_summary" for all starter actions

Avoid for now:

• freeform formula injection as a first-class starter action input
• schema mutation, attachment upload, and destructive delete flows
• automatic publish of record-creation actions

Starter Airtable actions

Automatic read actions

• list-records -> GET /v0/{baseId}/{tableIdOrName}
• get-record -> GET /v0/{baseId}/{tableIdOrName}/{recordId}

Approval-friendly write actions

• create-record -> POST /v0/{baseId}/{tableIdOrName}

Why these actions

These routes fit Harbor's current safe model because they:

• stay under one fixed Airtable API origin
• use explicit base, table, and record identifiers that operators supply at execution time
• keep optional query parameters typed and reviewable
• expose record creation as a named capability instead of arbitrary HTTP or raw credential access
• keep hidden auth entirely local to Harbor Node

Action Model notes

For Airtable actions, Harbor stores explicit path templates and typed parameter metadata such as:

• /v0/{baseId}/{tableIdOrName}
• /v0/{baseId}/{tableIdOrName}/{recordId}

At execution time, callers supply values by location:

• input.path for path placeholders
• input.query for typed query parameters
• input.body for JSON request bodies

Example table listing request:

{
  "path": {
    "baseId": "appExampleBase123",
    "tableIdOrName": "tblTasks456"
  },
  "query": {
    "pageSize": 25,
    "view": "Grid view"
  }
}

Example record lookup request:

{
  "path": {
    "baseId": "appExampleBase123",
    "tableIdOrName": "tblTasks456",
    "recordId": "recAbCdEf123456"
  }
}

Example create request:

{
  "path": {
    "baseId": "appExampleBase123",
    "tableIdOrName": "tblTasks456"
  },
  "body": {
    "fields": {
      "Name": "Prepare launch brief",
      "Status": "In Progress"
    },
    "typecast": true
  }
}

Harbor fills path placeholders safely, validates query values against the stored schema, and keeps the request URL Harbor-owned.

Safety note for record creation

create-record stays on require_approval because Airtable writes can trigger automations, notify users, and affect downstream views or integrations. Harbor should treat that as an explicit, reviewable capability.

Suggested operator workflow

1. Import the Airtable Dock entry from Dock / Hub.
2. Configure the local Airtable bearer token in Harbor Node with the scopes you need.
3. Use list-records first to confirm the port is working.
4. Use get-record to inspect a known record before adding write flows.
5. Keep create-record on require_approval unless there is a very deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing Airtable Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path or bounded path-template actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden Airtable auth
• widen Airtable into a generic arbitrary database or HTTP proxy

Current update strategy

For now, Airtable updates are manual:

• update the Dock / Hub Airtable integration document in apps/hub/catalog/integrations/airtable/airtable-web-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future options such as filtered record search helpers or attachment workflows are intentionally deferred until Harbor has clearer policy controls for data mutation and freeform formula use.

Official reference starting points

• Airtable Web API root: https://airtable.com/developers/web/api
• List records: https://airtable.com/developers/web/api/list-records
• Get record: https://airtable.com/developers/web/api/get-record
• Create records: https://airtable.com/developers/web/api/create-records