Grist docs API
Workspaces contain collections of Grist documents.
OpenAPI Specification
openapi: 3.0.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