grist-reference

name	grist-reference
description	Grist API reference documentation for the grist-mcp-server project. Use when implementing or modifying Grist MCP tools, working with Grist cell values, UserActions, column types, widget options, database schema, or pages/widgets. This skill provides authoritative API specifications.

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:

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