grist-reference

gwhthompson's avatarfrom gwhthompson

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025
[API Helpers]

When & Why to Use This Skill

This Claude skill provides authoritative Grist API reference documentation, enabling developers to seamlessly implement MCP tools, manage database schemas, and configure complex UI components. It streamlines the development process by providing instant access to OpenAPI specifications, TypeScript type definitions, and metadata structures for the Grist platform.

Use Cases

  • Developing MCP Tools: Quickly access OpenAPI specifications and TypeScript types to build, modify, or debug Grist Model Context Protocol (MCP) servers.
  • Database Schema Management: Reference metadata table structures and column definitions to design, query, or migrate Grist database schemas effectively.
  • UI & Widget Configuration: Utilize detailed guides on layout specifications and widget linking to programmatically create custom pages and interactive dashboards.
  • Data Integration & Encoding: Correctly encode cell values and handle complex data types (like RefValue or DateValue) using authoritative TypeScript definitions.
  • API Response Validation: Verify action results and implement robust error handling patterns by referencing the specialized /apply endpoint documentation.
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