Grist API Reference

This skill provides comprehensive Grist API documentation for developing the grist-mcp-server.

Quick Reference

Reference Files

grist-api.yml (~2100 lines)

OpenAPI 3.0 specification for the Grist REST API.

Grep patterns:

• paths: – API endpoints
• components/schemas – Data schemas
• CellValue – Cell value encoding
• UserAction – User action format

Use for: Endpoint parameters, request/response schemas, authentication

grist-api.d.ts (~2030 lines)

Complete TypeScript type definitions for Grist API.

Grep patterns:

• type.*Value – Cell value types (RefValue, DateValue, etc.)
• interface.*Options – Widget options interfaces
• UserAction – UserAction type definitions
• GristObjCode – Encoding codes (L, D, R, etc.)
• PERMISSION – Permission system reference

Use for: Type definitions, cell value encoding, widget options format

grist-database-schema.md (~573 lines)

Grist metadata tables and database structure.

Key sections:

• _grist_Tables – Table definitions
• _grist_Tables_column – Column schema
• _grist_Views_section – Widget definitions
• _grist_ACLRules – Access control

Use for: Understanding metadata structure, foreign key relationships

grist-pages-widgets.md (~658 lines)

Practical guide for pages (views) and widgets (view sections).

Key sections:

• CreateViewSection – Widget creation action
• Layout Structure – layoutSpec JSON format
• Widget Linking – linkSrcSectionRef, linkSrcColRef
• Sorting – sortColRefs format
• Filtering – _grist_Filters table

Use for: Page/widget creation, layout configuration, widget linking

grist-apply-endpoint.md (~490 lines)

Guide for verifying actions via /apply endpoint.

Key sections:

• ApplyUAResult – Response structure
• retValues – Return value verification
• Error Handling – Error response formats
• Best Practices – Safe access patterns

Use for: Validating action results, error handling patterns

Common Tasks

Implementing a new tool:

1. Load grist-api.yml for endpoint schema
2. Load grist-api.d.ts for TypeScript types

Working with cell values:

1. Load grist-api.d.ts – search for GristObjCode and CellValue

Creating pages/widgets:

1. Load grist-pages-widgets.md for CreateViewSection and layout format

Understanding metadata tables:

1. Load grist-database-schema.md for table schemas

Handling apply endpoint responses:

1. Load grist-apply-endpoint.md for response verification