Grist docs API
Workspaces contain collections of Grist documents.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/grist-docs-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
description: 'An API for manipulating Grist sites, workspaces, and documents.
# Authentication
<SecurityDefinitions />
'
version: 1.0.1
title: Grist attachments Docs API
servers:
- url: https://{gristhost}/api
variables:
subdomain:
description: The team name, or `docs` for personal areas
default: docs
security:
- ApiKey: []
tags:
- name: docs
description: Workspaces contain collections of Grist documents.
paths:
/workspaces/{workspaceId}/docs:
post:
operationId: createDoc
tags:
- docs
summary: Create an empty document
parameters:
- $ref: '#/components/parameters/workspaceIdPathParam'
requestBody:
description: settings for the document
content:
application/json:
schema:
$ref: '#/components/schemas/DocParameters'
required: true
responses:
200:
description: The document id
content:
application/json:
schema:
type: string
description: a unique identifier for the document
example: 9PJhBDZPyCNoayZxaCwFfS
/workspaces/{workspaceId}/import:
post:
operationId: importDoc
tags:
- docs
summary: Import an existing document
parameters:
- $ref: '#/components/parameters/workspaceIdPathParam'
requestBody:
description: settings for the document
content:
multipart/form-data:
schema:
type: object
properties:
upload:
description: Contents of a .grist file, as a standard multipart/form-data file entry
type: string
format: binary
documentName:
type: string
example: Example Doc
required: true
responses:
200:
description: The document id
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: a unique identifier for the document
example: 9PJhBDZPyCNoayZxaCwFfS
/docs:
post:
operationId: createDocUnified
tags:
- docs
summary: Create a document
description: 'A unified endpoint for creating documents. Can create an empty document,
copy an existing document, or import a file.
- To create an empty unsaved document: provide no parameters
- To create an empty saved document: provide `workspaceId`
- To copy an existing document: provide `sourceDocumentId`, `workspaceId`, and `documentName`
- To import a file: use multipart/form-data with a file upload and optional `workspaceId`
'
requestBody:
description: settings for the document
content:
application/json:
schema:
type: object
properties:
workspaceId:
type: integer
description: The workspace to save the document in. If omitted, creates an unsaved document.
example: 97
documentName:
type: string
description: Name for the new document (required when copying)
example: My Document
sourceDocumentId:
type: string
description: ID of document to copy from. Requires workspaceId and documentName.
example: mNnQ2PXndhXm
asTemplate:
type: boolean
description: When copying, if true, copy structure only without data
example: false
timezone:
type: string
description: Timezone for the document
example: America/New_York
multipart/form-data:
schema:
type: object
properties:
upload:
description: File to import (.grist, .xlsx, .csv, etc.)
type: string
format: binary
workspaceId:
type: integer
description: The workspace to save the document in
documentName:
type: string
description: Name for the imported document
responses:
200:
description: The document id
content:
application/json:
schema:
type: string
description: a unique identifier for the document
example: 9PJhBDZPyCNoayZxaCwFfS
/docs/{docId}:
get:
operationId: describeDoc
tags:
- docs
summary: Describe a document
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: A document's metadata
content:
application/json:
schema:
$ref: '#/components/schemas/DocWithWorkspace'
patch:
operationId: modifyDoc
tags:
- docs
summary: Modify document metadata (but not its contents)
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: the changes to make
content:
application/json:
schema:
$ref: '#/components/schemas/DocParameters'
required: true
responses:
200:
description: Success
delete:
operationId: deleteDoc
tags:
- docs
summary: Delete a document
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Success
/docs/{docId}/remove:
post:
operationId: removeDoc
tags:
- docs
summary: Move document to trash
description: 'Soft-delete the document by moving it to trash. The document can be
restored using the unremove endpoint. If the `permanent` query parameter
is set to true, the document is permanently deleted instead.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: permanent
schema:
type: boolean
description: If true, permanently delete instead of moving to trash
responses:
200:
description: Document moved to trash (or permanently deleted)
/docs/{docId}/unremove:
post:
operationId: unremoveDoc
tags:
- docs
summary: Restore document from trash
description: 'Recover a document that was previously soft-deleted. Only works if the
document is still in the trash.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document restored successfully
/docs/{docId}/move:
patch:
operationId: moveDoc
tags:
- docs
summary: Move document to another workspace.
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: the target workspace
content:
application/json:
schema:
type: object
required:
- workspace
properties:
workspace:
type: integer
example: 597
responses:
200:
description: Document moved successfully. Returns empty body.
/docs/{docId}/pin:
patch:
operationId: pinDoc
tags:
- docs
summary: Pin a document
description: 'Pin the document so it appears in a prominent location. Pinned documents
are displayed at the top of workspace listings for easy access.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document pinned successfully
/docs/{docId}/unpin:
patch:
operationId: unpinDoc
tags:
- docs
summary: Unpin a document
description: Remove the pinned status from a document.
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document unpinned successfully
/docs/{docId}/disable:
post:
operationId: disableDoc
tags:
- docs
summary: Disable a document.
description: 'Disabled documents cannot be accessed or modified. Moving and
renaming a disabled doc is also forbidden, as well as
accessing or submitting published forms associated to a
disabled document.
Disabled documents, however, can be moved to and restored from
the trash.
The operation is non-destructive. Disabled documents can be
re-enabled.
Only admin accounts can disable a document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document disabled successfully. Returns empty body.
403:
description: The caller is not allowed to disable this document
404:
description: The document is not found
/docs/{docId}/enable:
post:
operationId: enableDoc
tags:
- docs
summary: Enable a document.
description: 'If a document has been previously disabled, this will restore
all former access to a document, including access to its
associated published forms.
Only admin accounts can enable a document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document enabled successfully. Returns empty body.
403:
description: The caller is not allowed to enable this document
404:
description: The document is not found
/docs/{docId}/copy:
post:
operationId: copyDoc
tags:
- docs
summary: Copies a document to a workspace.
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: the target workspace
content:
application/json:
schema:
type: object
required:
- workspaceId
- documentName
properties:
workspaceId:
type: integer
example: 597
documentName:
type: string
example: Example Doc
asTemplate:
type: boolean
description: Remove all data and history but keep the structure to use the document as a template
responses:
200:
description: The document id
content:
application/json:
schema:
description: a unique identifier for the document
type: string
example: '145'
/docs/{docId}/fork:
post:
operationId: forkDoc
tags:
- docs
summary: Fork a document
description: 'Create a fork of a document. A fork is a personal copy that tracks its relationship
to the original document. Forks can be used to experiment with changes before
applying them to the original.
The fork will have a new docId and urlId that encode the relationship to the trunk
(original) document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Fork created successfully
content:
application/json:
schema:
type: object
required:
- forkId
- docId
- urlId
properties:
forkId:
type: string
description: The unique identifier for this fork
example: abc123
docId:
type: string
description: The full document ID of the fork
example: XXXXX~abc123
urlId:
type: string
description: The URL-friendly ID of the fork
example: UUUUU~abc123
400:
description: Cannot fork a document that's already a fork
403:
description: Insufficient access to document to copy it entirely
/docs/{docId}/access:
get:
operationId: listDocAccess
tags:
- docs
summary: List users with access to document
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Users with access to document
content:
application/json:
schema:
$ref: '#/components/schemas/DocAccessRead'
patch:
operationId: modifyDocAccess
tags:
- docs
summary: Change who has access to document
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
description: the changes to make
content:
application/json:
schema:
type: object
required:
- delta
properties:
delta:
$ref: '#/components/schemas/DocAccessWrite'
required: true
responses:
200:
description: Success
/docs/{docId}/usersForViewAs:
get:
operationId: getUsersForViewAs
tags:
- docs
summary: Get users for 'View As' feature
description: 'Get users that can be used with the "View As" feature for testing access rules.
Only document owners can call this endpoint.
Users are drawn from:
- Users the document is shared with
- Users mentioned in user attribute tables
- Predefined example users
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Users available for View As
content:
application/json:
schema:
type: object
properties:
users:
type: array
description: Users the document is shared with
items:
$ref: '#/components/schemas/User'
attributeTableUsers:
type: array
description: Users found in user attribute tables
items:
$ref: '#/components/schemas/User'
exampleUsers:
type: array
description: Predefined example users
items:
$ref: '#/components/schemas/User'
/docs/{docId}/download:
get:
operationId: downloadDoc
tags:
- docs
summary: Content of document, as an Sqlite file
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: nohistory
schema:
type: boolean
description: Remove document history (can significantly reduce file size)
required: false
- in: query
name: template
schema:
type: boolean
description: Remove all data and history but keep the structure to use the document as a template
required: false
responses:
200:
description: A document's content in Sqlite form
content:
application/x-sqlite3:
schema:
type: string
format: binary
/docs/{docId}/download/xlsx:
get:
operationId: downloadDocXlsx
tags:
- docs
summary: Content of document, as an Excel file
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- $ref: '#/components/parameters/headerQueryParam'
- in: query
name: tableId
schema:
type: string
description: Name of a table (normalized).
responses:
200:
description: A document's content in Excel form
content:
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
schema:
type: string
format: binary
/docs/{docId}/download/csv:
get:
operationId: downloadDocCsv
tags:
- docs
summary: Content of table, as a CSV file
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: tableId
schema:
type: string
description: Name of a table (normalized).
required: true
- $ref: '#/components/parameters/headerQueryParam'
responses:
200:
description: A table's content in CSV form
content:
text/csv:
schema:
type: string
/docs/{docId}/download/tsv:
get:
operationId: downloadDocTsv
tags:
- docs
summary: Content of table, as a TSV file
description: Download table data as tab-separated values.
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: tableId
schema:
type: string
description: Name of a table (normalized).
required: true
- $ref: '#/components/parameters/headerQueryParam'
responses:
200:
description: A table's content in TSV form
content:
text/tab-separated-values:
schema:
type: string
/docs/{docId}/download/dsv:
get:
operationId: downloadDocDsv
tags:
- docs
summary: Content of table, as a DSV file
description: Download table data using a custom delimiter (💩).
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: tableId
schema:
type: string
description: Name of a table (normalized).
required: true
- $ref: '#/components/parameters/headerQueryParam'
responses:
200:
description: A table's content in DSV form
content:
text/plain:
schema:
type: string
/docs/{docId}/download/table-schema:
get:
operationId: downloadTableSchema
tags:
- docs
summary: The schema of a table
description: The schema follows [frictionlessdata's table-schema standard](https://specs.frictionlessdata.io/table-schema/).
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: tableId
schema:
type: string
description: Name of a table (normalized).
required: true
- $ref: '#/components/parameters/headerQueryParam'
responses:
200:
description: A table's table-schema in JSON format.
content:
text/json:
schema:
$ref: '#/components/schemas/TableSchemaResult'
/docs/{docId}/snapshots:
get:
operationId: listSnapshots
tags:
- docs
summary: List document snapshots
description: 'Returns a list of snapshots (backups) of the document. Snapshots are created
automatically as the document is edited. Most recent snapshots are listed first.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: raw
schema:
type: boolean
description: If true, returns all snapshots including those not in the snapshot inventory
responses:
200:
description: List of snapshots
content:
application/json:
schema:
type: object
required:
- snapshots
properties:
snapshots:
type: array
items:
type: object
required:
- snapshotId
- lastModified
- docId
properties:
snapshotId:
type: string
description: Unique identifier for the snapshot
lastModified:
type: string
format: date-time
description: When the snapshot was created
docId:
type: string
description: Document ID that can be used to open this snapshot
/docs/{docId}/snapshots/remove:
post:
operationId: removeSnapshots
tags:
- docs
summary: Remove document snapshots
description: 'Remove specific snapshots from a document''s backup history.
Only document owners can remove snapshots.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
content:
application/json:
schema:
type: object
properties:
snapshotIds:
type: array
items:
type: string
description: List of snapshot IDs to remove
example:
snapshotIds:
- abc123
- def456
responses:
200:
description: Snapshots removed
content:
application/json:
schema:
type: object
properties:
snapshotIds:
type: array
items:
type: string
description: The snapshot IDs that were removed
/docs/{docId}/states:
get:
operationId: getStates
tags:
- docs
summary: Get document action history states
description: 'Returns a list of document states representing the action history.
Each state has a sequential number (n) and a hash (h) that uniquely
identifies that point in history. Most recent state is first.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: List of document states
content:
application/json:
schema:
type: object
required:
- states
properties:
states:
type: array
items:
type: object
required:
- n
- h
properties:
n:
type: integer
description: Sequential action number
h:
type: string
description: Hash identifier for this state
/docs/{docId}/compare:
get:
operationId: compareVersions
tags:
- docs
summary: Compare document versions
description: 'Compare two versions of the same document by their state hashes.
Returns details about what changed between the versions.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: left
schema:
type: string
description: Hash of the left version to compare (defaults to HEAD)
- in: query
name: right
schema:
type: string
description: Hash of the right version to compare (defaults to HEAD)
- in: query
name: maxRows
schema:
type: integer
description: Maximum number of row changes to include in details
responses:
200:
description: Comparison result
content:
application/json:
schema:
$ref: '#/components/schemas/DocComparison'
403:
description: Insufficient access to compare documents
/docs/{docId}/compare/{docId2}:
get:
operationId: compareDocuments
tags:
- docs
summary: Compare two documents
description: 'Compare this document with another document. Useful for comparing
a fork with its trunk document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- name: docId2
in: path
required: true
schema:
type: string
description: ID of the document to compare with
- in: query
name: detail
schema:
type: boolean
description: If true, include detailed change information
- in: query
name: maxRows
schema:
type: integer
description: Maximum number of row changes to include
responses:
200:
description: Comparison result
content:
application/json:
schema:
$ref: '#/components/schemas/DocComparison'
403:
description: Insufficient access to compare documents
/docs/{docId}/states/remove:
post:
operationId: deleteActions
tags:
- docs
summary: Truncate the document's action history
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
content:
application/json:
schema:
type: object
required:
- keep
properties:
keep:
type: integer
description: The number of the latest history actions to keep
example:
keep: 3
/docs/{docId}/proposals:
get:
operationId: listProposals
tags:
- docs
summary: List change proposals
description: 'List proposals associated with a document. Proposals are suggested changes
from forks that can be reviewed and applied to the trunk document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: outgoing
schema:
type: boolean
description: If true, list proposals where this document is the source. Otherwise list proposals where this document is the destination.
responses:
200:
description: List of proposals
content:
application/json:
schema:
type: object
properties:
proposals:
type: array
items:
type: object
properties:
id:
type: integer
description: Proposal ID
srcDocId:
type: string
description: Source document (fork) ID
destDocId:
type: string
description: Destination document (trunk) ID
retracted:
type: boolean
description: Whether the proposal has been retracted
comparison:
$ref: '#/components/schemas/DocComparison'
/docs/{docId}/propose:
post:
operationId: createProposal
tags:
- docs
summary: Create a change proposal
description: 'Create a proposal from a fork to its trunk document. The proposal contains
the comparison of changes between the fork and trunk.
This endpoint can only be called on a fork document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
content:
application/json:
schema:
type: object
properties:
retracted:
type: boolean
description: Set to true to retract an existing proposal
default: false
responses:
200:
description: Proposal created
content:
application/json:
schema:
type: object
properties:
id:
type: integer
description: Proposal ID
comparison:
$ref: '#/components/schemas/DocComparison'
400:
description: Can only propose from a fork
/docs/{docId}/proposals/{proposalId}/apply:
post:
operationId: applyProposal
tags:
- docs
summary: Apply a change proposal
description: 'Apply a proposal''s changes to the document. This merges the fork''s
changes into the trunk document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- name: proposalId
in: path
required: true
schema:
type: integer
description: ID of the proposal to apply
responses:
200:
description: Proposal applied successfully
content:
application/json:
schema:
type: object
properties:
proposalId:
type: integer
changes:
type: object
description: Summary of changes applied
/docs/{docId}/force-reload:
post:
operationId: forceReload
tags:
- docs
summary: Reload a document
description: Closes and reopens the document, forcing the python engine to restart.
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Document reloaded successfully
/docs/{docId}/flush:
post:
operationId: flushDoc
tags:
- docs
summary: Flush document to storage
description: 'Ensure all pending changes to the document are written to persistent storage.
Returns true if the document was flushed, false if the document was not open.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
responses:
200:
description: Flush result
content:
application/json:
schema:
type: boolean
description: True if document was flushed, false if document was not open
/docs/{docId}/assign:
post:
operationId: assignDoc
tags:
- docs
summary: Reassign document to appropriate worker
description: 'Administrative endpoint that checks if a document is assigned to the expected
worker group and frees it for reassignment if not. Used for load balancing
and maintenance operations.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
- in: query
name: group
schema:
type: string
description: Update the document's worker group (requires special permit)
responses:
200:
description: Assignment result
content:
application/json:
schema:
type: boolean
description: True if document was freed for reassignment
/docs/{docId}/replace:
post:
operationId: replaceDoc
tags:
- docs
summary: Replace document content
description: 'Replace the current document content with content from another source.
Can restore from a snapshot or copy from another document.
'
parameters:
- $ref: '#/components/parameters/docIdPathParam'
requestBody:
content:
application/json:
schema:
type: object
properties:
sourceDocId:
type: string
description: ID of document to copy content from
snapshotId:
type: string
description: ID of snapshot to restore from
resetTutorialMetadata:
type: boolean
description: Reset tutorial progress when replacing (for tutorial forks)
responses:
200
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/grist/refs/heads/main/openapi/grist-docs-api-openapi.yml