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