grist-reference
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.
When & Why to Use This Skill
The Grist API Reference skill serves as an authoritative technical guide for developers building or maintaining the grist-mcp-server. It provides instant access to comprehensive documentation, including OpenAPI specifications, TypeScript type definitions, and database schema details. By offering precise technical context, this skill helps developers implement Grist MCP tools accurately, manage complex cell values, and configure database layouts without manual documentation searches.
Use Cases
- 1. API Integration & Development: Use the OpenAPI 3.0 specifications to implement REST API endpoints, request schemas, and authentication for Grist-based applications.
- 2. Type-Safe Programming: Reference TypeScript definitions to correctly handle Grist-specific data types like RefValue, DateValue, and GristObjCode encoding.
- 3. Database Schema Mapping: Explore metadata tables and column definitions to understand foreign key relationships and underlying database structures.
- 4. UI and Widget Customization: Access detailed guides for creating pages, configuring layoutSpec JSON, and implementing widget linking strategies.
- 5. Action Validation and Debugging: Utilize the /apply endpoint documentation to verify return values and implement robust error-handling patterns.
| 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 endpointscomponents/schemas- Data schemasCellValue- Cell value encodingUserAction- 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 interfacesUserAction- UserAction type definitionsGristObjCode- 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 actionLayout Structure- layoutSpec JSON formatWidget Linking- linkSrcSectionRef, linkSrcColRefSorting- sortColRefs formatFiltering- _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 structureretValues- Return value verificationError Handling- Error response formatsBest Practices- Safe access patterns
Use for: Validating action results, error handling patterns
Common Tasks
Implementing a new tool:
- Load
grist-api.ymlfor endpoint schema - Load
grist-api.d.tsfor TypeScript types
Working with cell values:
- Load
grist-api.d.ts- search forGristObjCodeandCellValue
Creating pages/widgets:
- Load
grist-pages-widgets.mdfor CreateViewSection and layout format
Understanding metadata tables:
- Load
grist-database-schema.mdfor table schemas
Handling apply endpoint responses:
- Load
grist-apply-endpoint.mdfor response verification