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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

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.
namegrist-reference
descriptionGrist 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