Airtable API

The Airtable API lets you connect an Airtable base, explore its schema, fetch records, and use that data to generate PDFs. These endpoints act as a proxy to the Airtable API, handling authentication and formatting records for template rendering.

Tip

For a step-by-step walkthrough, see the Airtable Integration Guide.

Endpoints Overview

Method	Endpoint	Description
POST	/v1/airtable/connect	Validate an Airtable token and list accessible bases
GET	/v1/airtable/bases/:baseId/tables	List tables in a base
GET	/v1/airtable/bases/:baseId/tables/:tableId/schema	Get field schema for a table
GET	/v1/airtable/bases/:baseId/tables/:tableId/records	Fetch sample records
GET	/v1/airtable/bases/:baseId/tables/:tableId/records/:recordId	Get a single record

---

POST /v1/airtable/connect

POST /v1/airtable/connect

Validate an Airtable Personal Access Token (PAT) and return a list of accessible bases. This is the first step in the Airtable integration flow.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer gk_your_api_key
Content-Type	Yes	application/json

Body

{
  "apiKey": "patXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Parameters

Parameter	Type	Required	Description
apiKey	string	Yes	Airtable Personal Access Token (pat...) or legacy API key (key...)

Response

Success (200)

{
  "success": true,
  "bases": [
    {
      "id": "appXXXXXXXXXXXXXX",
      "name": "Sales Pipeline",
      "permissionLevel": "create"
    },
    {
      "id": "appYYYYYYYYYYYYYY",
      "name": "Invoices",
      "permissionLevel": "read"
    }
  ],
  "message": "Connected successfully. Found 2 accessible base(s)."
}

Field	Type	Description
success	boolean	Whether the connection succeeded
bases	array	List of accessible Airtable bases
bases[].id	string	Base ID (starts with app)
bases[].name	string	Human-readable base name
bases[].permissionLevel	string	Permission level (read, comment, edit, create)
message	string	Summary message

Error Responses

400 Bad Request — Invalid key format

{
  "error": "Invalid Airtable API key format. Keys should start with 'pat' (personal access token) or 'key' (legacy).",
  "code": "INVALID_KEY_FORMAT"
}

401 Unauthorized — Invalid token

{
  "error": "Failed to connect to Airtable. Please check your API key.",
  "code": "AIRTABLE_AUTH_ERROR"
}

Code Examples

cURL

curl -X POST https://api.glyph.you/v1/airtable/connect \
  -H "Authorization: Bearer gk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "patXXXXXXXXXXXXXX.XXXX"}'

JavaScript

const response = await fetch('https://api.glyph.you/v1/airtable/connect', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gk_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    apiKey: 'patXXXXXXXXXXXXXX.XXXX'
  })
});

const { success, bases } = await response.json();

if (success) {
  for (const base of bases) {
    console.log(`${base.name} (${base.id}) - ${base.permissionLevel}`);
  }
}

Python

import requests

response = requests.post(
    'https://api.glyph.you/v1/airtable/connect',
    headers={
        'Authorization': 'Bearer gk_your_api_key',
        'Content-Type': 'application/json'
    },
    json={'apiKey': 'patXXXXXXXXXXXXXX.XXXX'}
)

result = response.json()

if result['success']:
    for base in result['bases']:
        print(f"{base['name']} ({base['id']}) - {base['permissionLevel']}")

---

GET /v1/airtable/bases/:baseId/tables

GET /v1/airtable/bases/:baseId/tables

List all tables in an Airtable base with their field counts and view counts.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer gk_your_api_key
X-Airtable-Key	Yes	Airtable PAT for accessing the base

Path Parameters

Parameter	Type	Description
baseId	string	Airtable base ID (e.g. appXXXXXXXXXXXXXX)

Response

{
  "success": true,
  "baseId": "appXXXXXXXXXXXXXX",
  "tables": [
    {
      "id": "tblXXXXXXXXXXXXXX",
      "name": "Orders",
      "description": "All customer orders",
      "primaryFieldId": "fldXXXXXXXXXXXXXX",
      "fieldCount": 12,
      "viewCount": 3
    }
  ]
}

Field	Type	Description
tables[].id	string	Table ID
tables[].name	string	Table name
tables[].description	string	Table description (if set in Airtable)
tables[].primaryFieldId	string	ID of the primary field
tables[].fieldCount	number	Number of fields in the table
tables[].viewCount	number	Number of views

Code Examples

cURL

curl https://api.glyph.you/v1/airtable/bases/appXXXXXXXXXXXXXX/tables \
  -H "Authorization: Bearer gk_your_api_key" \
  -H "X-Airtable-Key: patXXXXXXXXXXXXXX.XXXX"

JavaScript

const response = await fetch(
  'https://api.glyph.you/v1/airtable/bases/appXXXXXXXXXXXXXX/tables',
  {
    headers: {
      'Authorization': 'Bearer gk_your_api_key',
      'X-Airtable-Key': 'patXXXXXXXXXXXXXX.XXXX'
    }
  }
);

const { tables } = await response.json();
for (const table of tables) {
  console.log(`${table.name}: ${table.fieldCount} fields, ${table.viewCount} views`);
}

---

GET /v1/airtable/bases/:baseId/tables/:tableId/schema

GET /v1/airtable/bases/:baseId/tables/:tableId/schema

Get the detailed field schema for a table, including field types, descriptions, and AI-optimized schema output.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer gk_your_api_key
X-Airtable-Key	Yes	Airtable PAT

Path Parameters

Parameter	Type	Description
baseId	string	Airtable base ID
tableId	string	Table ID or table name

Response

{
  "success": true,
  "baseId": "appXXXXXXXXXXXXXX",
  "table": {
    "id": "tblXXXXXXXXXXXXXX",
    "name": "Orders",
    "description": "All customer orders",
    "primaryFieldId": "fldXXXXXXXXXXXXXX"
  },
  "fields": [
    {
      "id": "fldXXXXXXXXXXXXXX",
      "name": "Order Number",
      "type": "singleLineText",
      "description": "Unique order identifier",
      "options": null
    },
    {
      "id": "fldYYYYYYYYYYYYYY",
      "name": "Total",
      "type": "currency",
      "description": null,
      "options": {
        "precision": 2,
        "symbol": "$"
      }
    }
  ],
  "views": [
    {
      "id": "viwXXXXXXXXXXXXXX",
      "name": "Grid view",
      "type": "grid"
    }
  ],
  "aiSchema": "Order Number (singleLineText), Total (currency), ..."
}

Field	Type	Description
fields[].id	string	Field ID
fields[].name	string	Human-readable field name
fields[].type	string	Airtable field type (e.g. singleLineText, currency, multipleRecordLinks)
fields[].description	string	Field description (if set)
fields[].options	object	Type-specific options (precision, choices, linked table, etc.)
views	array	Available views for filtering records
aiSchema	string	AI-optimized schema summary for template generation

Code Examples

cURL

curl https://api.glyph.you/v1/airtable/bases/appXXXX/tables/tblXXXX/schema \
  -H "Authorization: Bearer gk_your_api_key" \
  -H "X-Airtable-Key: patXXXXXXXXXXXXXX.XXXX"

---

GET /v1/airtable/bases/:baseId/tables/:tableId/records

GET /v1/airtable/bases/:baseId/tables/:tableId/records

Fetch sample records from a table. Records are returned in both raw Airtable format and a template-friendly format.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer gk_your_api_key
X-Airtable-Key	Yes	Airtable PAT

Path Parameters

Parameter	Type	Description
baseId	string	Airtable base ID
tableId	string	Table ID or table name

Query Parameters

Parameter	Type	Default	Description
maxRecords	number	5	Number of records to fetch (1-100)
view	string	—	Airtable view name or ID to filter records

Response

{
  "success": true,
  "baseId": "appXXXXXXXXXXXXXX",
  "tableId": "tblXXXXXXXXXXXXXX",
  "tableName": "Orders",
  "recordCount": 5,
  "records": [
    {
      "Order Number": "ORD-001",
      "Customer": "Acme Corp",
      "Total": "$1,500.00",
      "Status": "Paid"
    }
  ],
  "rawRecords": [
    {
      "id": "recXXXXXXXXXXXXXX",
      "createdTime": "2026-01-15T10:00:00.000Z",
      "fields": {
        "Order Number": "ORD-001",
        "Customer": "Acme Corp",
        "Total": 1500,
        "Status": { "name": "Paid", "color": "greenBright" }
      }
    }
  ]
}

Field	Type	Description
records	array	Template-friendly records with formatted values (currency symbols, dates, etc.)
rawRecords	array	Raw Airtable records with original field types
rawRecords[].id	string	Airtable record ID
rawRecords[].fields	object	Raw field values

Tip

Use the records array (template-friendly format) when passing data to /v1/create or /v1/preview. Use rawRecords for debugging or when you need the original Airtable field types.

Code Examples

cURL

# Fetch 10 records from a specific view
curl "https://api.glyph.you/v1/airtable/bases/appXXXX/tables/tblXXXX/records?maxRecords=10&view=Grid%20view" \
  -H "Authorization: Bearer gk_your_api_key" \
  -H "X-Airtable-Key: patXXXXXXXXXXXXXX.XXXX"

JavaScript

const baseId = 'appXXXXXXXXXXXXXX';
const tableId = 'tblXXXXXXXXXXXXXX';

const response = await fetch(
  `https://api.glyph.you/v1/airtable/bases/${baseId}/tables/${tableId}/records?maxRecords=10`,
  {
    headers: {
      'Authorization': 'Bearer gk_your_api_key',
      'X-Airtable-Key': airtableToken
    }
  }
);

const { records, recordCount } = await response.json();
console.log(`Fetched ${recordCount} records`);

// Use the first record to generate a PDF
const pdfResponse = await fetch('https://api.glyph.you/v1/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer gk_your_api_key',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    data: records[0],
    intent: 'professional invoice'
  })
});

---

GET /v1/airtable/bases/:baseId/tables/:tableId/records/:recordId

GET /v1/airtable/bases/:baseId/tables/:tableId/records/:recordId

Fetch a single record by its Airtable record ID.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer gk_your_api_key
X-Airtable-Key	Yes	Airtable PAT

Path Parameters

Parameter	Type	Description
baseId	string	Airtable base ID
tableId	string	Table ID or table name
recordId	string	Airtable record ID (starts with rec)

Response

{
  "success": true,
  "baseId": "appXXXXXXXXXXXXXX",
  "tableId": "tblXXXXXXXXXXXXXX",
  "tableName": "Orders",
  "record": {
    "Order Number": "ORD-001",
    "Customer": "Acme Corp",
    "Total": "$1,500.00"
  },
  "rawRecord": {
    "id": "recXXXXXXXXXXXXXX",
    "createdTime": "2026-01-15T10:00:00.000Z",
    "fields": {
      "Order Number": "ORD-001",
      "Customer": "Acme Corp",
      "Total": 1500
    }
  }
}

Code Examples

cURL

curl https://api.glyph.you/v1/airtable/bases/appXXXX/tables/tblXXXX/records/recXXXX \
  -H "Authorization: Bearer gk_your_api_key" \
  -H "X-Airtable-Key: patXXXXXXXXXXXXXX.XXXX"

---

Complete Workflow: Airtable to PDF

Here is a complete example that connects to Airtable, fetches a record, and generates a PDF:

const GLYPH_KEY = 'gk_your_api_key';
const AIRTABLE_TOKEN = 'patXXXXXXXXXXXXXX.XXXX';

// Step 1: Connect and find the base
const connectRes = await fetch('https://api.glyph.you/v1/airtable/connect', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${GLYPH_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ apiKey: AIRTABLE_TOKEN })
});
const { bases } = await connectRes.json();
const baseId = bases[0].id;

// Step 2: List tables
const tablesRes = await fetch(
  `https://api.glyph.you/v1/airtable/bases/${baseId}/tables`,
  {
    headers: {
      'Authorization': `Bearer ${GLYPH_KEY}`,
      'X-Airtable-Key': AIRTABLE_TOKEN
    }
  }
);
const { tables } = await tablesRes.json();
const tableId = tables[0].id;

// Step 3: Fetch records
const recordsRes = await fetch(
  `https://api.glyph.you/v1/airtable/bases/${baseId}/tables/${tableId}/records?maxRecords=1`,
  {
    headers: {
      'Authorization': `Bearer ${GLYPH_KEY}`,
      'X-Airtable-Key': AIRTABLE_TOKEN
    }
  }
);
const { records } = await recordsRes.json();

// Step 4: Generate PDF from the record data
const pdfRes = await fetch('https://api.glyph.you/v1/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${GLYPH_KEY}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    data: records[0],
    intent: 'professional invoice',
    style: 'stripe-clean'
  })
});

const pdf = await pdfRes.json();
console.log(`Generated: ${pdf.filename} (${pdf.size} bytes)`);

Error Responses

All Airtable endpoints share these common errors:

Status	Code	Description
400	VALIDATION_ERROR	Invalid request data
400	INVALID_KEY_FORMAT	Airtable key does not start with pat or key
400	MISSING_REQUIRED	Missing X-Airtable-Key header
401	AIRTABLE_AUTH_ERROR	Invalid Airtable token
404	NOT_FOUND	Table or record not found
502	AIRTABLE_ERROR	Failed to communicate with Airtable API

See Also

• Airtable Integration Guide — Step-by-step setup walkthrough
• Airtable Extension — Generate PDFs directly from Airtable
• POST /v1/create — Generate PDFs from Airtable data
• Templates Overview — Available document templates