Grist API (1.0.0)

An API for manipulating Grist sites, workspaces, and documents.

Authentication

API Key

Access to the Grist API is controlled by an Authorization header, which should contain the word 'Bearer', followed by a space, followed by your API key.

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "Authorization: Bearer XXXXXXXXXXX"

orgs

Team sites and personal spaces are called 'orgs' in the API.

List the orgs you have access to

get /orgs
https://docs.getgrist.com/api/orgs

This enumerates all the team sites or personal areas available.

Authorizations:

Responses

200

An array of organizations

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Describe an org

get /orgs/{orgId}
https://docs.getgrist.com/api/orgs/{orgId}
Authorizations:
path Parameters
orgId
required
any (OrgKey)

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Responses

200

An organization

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 42,
  • "name": "Grist Labs",
  • "domain": "gristlabs",
  • "owner":
    {
    },
  • "access": "owners",
  • "createdAt": "2019-09-13T15:42:35.000Z",
  • "updatedAt": "2019-09-13T15:42:35.000Z"
}

Modify an org

patch /orgs/{orgId}
https://docs.getgrist.com/api/orgs/{orgId}
Authorizations:
path Parameters
orgId
required
any (OrgKey)

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Request Body schema: application/json

the changes to make

name
string

Responses

200

Success

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "ACME Unlimited"
}

List users with access to org

get /orgs/{orgId}/access
https://docs.getgrist.com/api/orgs/{orgId}/access
Authorizations:
path Parameters
orgId
required
any (OrgKey)

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Responses

200

Users with access to org

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "users":
    [
    ]
}

Change who has access to org

patch /orgs/{orgId}/access
https://docs.getgrist.com/api/orgs/{orgId}/access
Authorizations:
path Parameters
orgId
required
any (OrgKey)

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Request Body schema: application/json

the changes to make

delta
required
object (OrgAccessWrite)

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "delta":
    {
    }
}

List workspaces and documents within an org

get /orgs/{orgId}/workspaces
https://docs.getgrist.com/api/orgs/{orgId}/workspaces
Authorizations:
path Parameters
orgId
required
any (OrgKey)

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Responses

200

An org's workspaces and documents

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 42,
  • "name": "Grist Labs",
  • "domain": "gristlabs",
  • "owner":
    {
    },
  • "access": "owners",
  • "createdAt": "2019-09-13T15:42:35.000Z",
  • "updatedAt": "2019-09-13T15:42:35.000Z",
  • "workspaces":
    [
    ]
}

Create an empty workspace

post /orgs/{orgId}/workspaces
https://docs.getgrist.com/api/orgs/{orgId}/workspaces
Authorizations:
path Parameters
orgId
required
any (OrgKey)

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Request Body schema: application/json

settings for the workspace

name
string

Responses

200

The workspace id

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Retreat Docs"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
155

workspaces

Sites can be organized into groups of documents called workspaces.

Create an empty workspace

post /orgs/{orgId}/workspaces
https://docs.getgrist.com/api/orgs/{orgId}/workspaces
Authorizations:
path Parameters
orgId
required
any (OrgKey)

This can be an integer id, or a string subdomain (e.g. gristlabs), or current if the org is implied by the domain in the url

Request Body schema: application/json

settings for the workspace

name
string

Responses

200

The workspace id

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Retreat Docs"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
155

Describe a workspace

get /workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Responses

200

A workspace

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 97,
  • "name": "Secret Plans",
  • "access": "owners",
  • "org":
    {
    }
}

Create an empty document

post /workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Request Body schema: application/json

settings for the document

name
string
isPinned
boolean

Responses

200

The document id

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Competitive Analysis",
  • "isPinned": false
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"8b97c8db-b4df-4b34-b72c-17459e70140a"

Modify a workspace

patch /workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Request Body schema: application/json

the changes to make

name
string

Responses

200

Success

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Retreat Docs"
}

Delete a workspace

delete /workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Responses

200

Success

List users with access to workspace

get /workspace/{workspaceId}/access
https://docs.getgrist.com/api/workspace/{workspaceId}/access
Authorizations:
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Responses

200

Users with access to workspace

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "maxInheritedRole": "owners",
  • "users":
    [
    ]
}

Change who has access to workspace

patch /workspace/{workspaceId}/access
https://docs.getgrist.com/api/workspace/{workspaceId}/access
Authorizations:
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Request Body schema: application/json

the changes to make

delta
required
object (WorkspaceAccessWrite)

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "delta":
    {
    }
}

docs

Workspaces contain collections of Grist documents.

Create an empty document

post /workspaces/{workspaceId}
https://docs.getgrist.com/api/workspaces/{workspaceId}
Authorizations:
path Parameters
workspaceId
required
integer (WorkspaceKey)

An integer id

Request Body schema: application/json

settings for the document

name
string
isPinned
boolean

Responses

200

The document id

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Competitive Analysis",
  • "isPinned": false
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"8b97c8db-b4df-4b34-b72c-17459e70140a"

Describe a document

get /docs/{docId}
https://docs.getgrist.com/api/docs/{docId}
Authorizations:
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

200

A document's metadata

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 145,
  • "name": "Project Lollipop",
  • "access": "owners",
  • "isPinned": true,
  • "urlId": null,
  • "workspace":
    {
    }
}

Modify document metadata (but not its contents)

patch /docs/{docId}
https://docs.getgrist.com/api/docs/{docId}
Authorizations:
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Request Body schema: application/json

the changes to make

name
string
isPinned
boolean

Responses

200

Success

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Competitive Analysis",
  • "isPinned": false
}

Delete a document

delete /docs/{docId}
https://docs.getgrist.com/api/docs/{docId}
Authorizations:
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

200

Success

Move document to another workspace in the same org.

patch /docs/{docId}/move
https://docs.getgrist.com/api/docs/{docId}/move
Authorizations:
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Request Body schema: application/json

the target workspace

workspace
required
integer

Responses

200

Success

Request samples

Content type
application/json
Copy
Expand all Collapse all