Grist API Reference

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

Quick Reference

Task Reference File

REST API endpoints grist-api.yml

TypeScript types, CellValue encoding grist-api.d.ts

Metadata tables, column definitions grist-database-schema.md

Pages, widgets, layouts, linking grist-pages-widgets.md

Apply endpoint, response verification grist-apply-endpoint.md

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:

• Load grist-api.yml for endpoint schema

• Load grist-api.d.ts for TypeScript types

Working with cell values:

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

Creating pages/widgets:

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

Understanding metadata tables:

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

Handling apply endpoint responses:

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