Grist API reference

New to Corsair? See API access, authentication, and error handling.

Attachments

get

attachments.get Get metadata for a specific attachment in a document Risk: read

await corsair.grist.api.attachments.get({ docId: 'doc123example', attachmentId: 1 });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`attachmentId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`fileName`	`string`	No	—
`fileSize`	`number`	No	—
`timeUploaded`	`string`	No	—

getTransferStatus

attachments.getTransferStatus Get current attachment transfer status for an external store Risk: read

await corsair.grist.api.attachments.getTransferStatus({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: Record<string, any>

list

attachments.list List metadata for attachments stored in a document Risk: read

await corsair.grist.api.attachments.list({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`filter`	`string`	No	—
`sort`	`string`	No	—
`limit`	`number`	No	—

Output

Name	Type	Required	Description
`records`	`object[]`	Yes	—

records full type

{
  id: number,
  fields: {
    fileName?: string,
    fileSize?: number,
    timeUploaded?: string
  }
}[]

removeUnused

attachments.removeUnused Delete unused attachments from a document Risk: destructive

await corsair.grist.api.attachments.removeUnused({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`expiredOnly`	`boolean`	No	—

Output: any

updateUsed

attachments.updateUsed Update attachment usage tracking in a document Risk: write

await corsair.grist.api.attachments.updateUsed({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: any

verifyFiles

attachments.verifyFiles Verify attachment file integrity for a document Risk: read

await corsair.grist.api.attachments.verifyFiles({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: any

Columns

add

columns.add Add new columns to a table in a document Risk: write

await corsair.grist.api.columns.add({ docId: 'doc123example', tableId: 'Table1', columns: [{ id: 'category', fields: { label: 'Category' } }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`columns`	`object[]`	Yes	—

columns full type

{
  id?: string,
  fields: Record<string, any>
}[]

Output

Name	Type	Required	Description
`columns`	`object[]`	Yes	—

columns full type

{
  id: string
}[]

delete

columns.delete Delete a column from a table Risk: destructive

await corsair.grist.api.columns.delete({ docId: 'doc123example', tableId: 'Table1', colId: 'category' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`colId`	`string`	Yes	—

Output: any

list

columns.list List columns and metadata for a table Risk: read

await corsair.grist.api.columns.list({ docId: 'doc123example', tableId: 'Table1' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`hidden`	`boolean`	No	—

Output

Name	Type	Required	Description
`columns`	`object[]`	Yes	—

columns full type

{
  id: string,
  fields: Record<string, any>
}[]

replace

columns.replace Add or update column definitions in a table Risk: write

await corsair.grist.api.columns.replace({ docId: 'doc123example', tableId: 'Table1', columns: [{ id: 'category', fields: { label: 'Category' } }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`columns`	`object[]`	Yes	—

columns full type

{
  id?: string,
  fields: Record<string, any>
}[]

Output: any

update

columns.update Modify column configurations or labels in a table Risk: write

await corsair.grist.api.columns.update({ docId: 'doc123example', tableId: 'Table1', columns: [{ id: 'category', fields: { label: 'Product Category' } }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`columns`	`object[]`	Yes	—

columns full type

{
  id: string,
  fields: Record<string, any>
}[]

Output: any

Docs

copy

docs.copy Copy a document to a workspace Risk: write

await corsair.grist.api.docs.copy({ docId: 'doc123example', workspaceId: 1, documentName: 'Inventory Copy' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`workspaceId`	`number`	Yes	—
`documentName`	`string`	Yes	—
`asTemplate`	`boolean`	No	—

Output: string

create

docs.create Create a new Grist document or copy from a template Risk: write

await corsair.grist.api.docs.create({ workspaceId: 1, documentName: 'Inventory' });

Input

Name	Type	Required	Description
`workspaceId`	`number`	No	—
`documentName`	`string`	No	—
`sourceDocumentId`	`string`	No	—
`asTemplate`	`boolean`	No	—
`timezone`	`string`	No	—

Output: string

createInWorkspace

docs.createInWorkspace Create an empty document inside a specific workspace Risk: write

await corsair.grist.api.docs.createInWorkspace({ workspaceId: 1, name: 'Inventory' });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—
`name`	`string`	Yes	—
`isPinned`	`boolean`	No	—

Output: string

delete

docs.delete Permanently delete a document Risk: destructive

await corsair.grist.api.docs.delete({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: any

fork

docs.fork Fork a document into a new unsaved document Risk: write

await corsair.grist.api.docs.fork({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output

Name	Type	Required	Description
`forkId`	`string`	Yes	—
`docId`	`string`	Yes	—
`urlId`	`string`	Yes	—

get

docs.get Describe document metadata and containing workspace Risk: read

await corsair.grist.api.docs.get({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output

Name	Type	Required	Description
`id`	`string`	Yes	—
`name`	`string`	Yes	—
`access`	`owners \| editors \| viewers \| members \| guests \| string \| null`	No	—
`isPinned`	`boolean`	No	—
`urlId`	`string \| null`	No	—
`workspace`	`object`	No	—

workspace full type

{
  id: number,
  name: string,
  access?: owners | editors | viewers | members | guests | string | null
}

listAccess

docs.listAccess List users with access permissions to a document Risk: read

await corsair.grist.api.docs.listAccess({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output

Name	Type	Required	Description
`maxInheritedRole`	`owners \| editors \| viewers \| members \| guests \| string \| null`	No	—
`users`	`object[]`	Yes	—

users full type

{
  id: number,
  name: string,
  email?: string,
  access?: owners | editors | viewers | members | guests | string | null,
  parentAccess?: owners | editors | viewers | members | guests | string | null
}[]

listSnapshots

docs.listSnapshots List historical snapshots of a document Risk: read

await corsair.grist.api.docs.listSnapshots({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`raw`	`boolean`	No	—

Output

Name	Type	Required	Description
`snapshots`	`object[]`	Yes	—

snapshots full type

{
  snapshotId: string,
  lastModified: string,
  docId: string
}[]

modifyAccess

docs.modifyAccess Change user access permissions for a document; sharing with a new email address sends that person an invitation Risk: destructive

await corsair.grist.api.docs.modifyAccess({ docId: 'doc123example', users: { 'user@example.com': 'owners' } });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`maxInheritedRole`	`owners \| editors \| viewers \| null`	No	—
`users`	`Record<string, owners \| editors \| viewers \| members \| null>`	Yes	—

Output: any

move

docs.move Move a document to a different workspace Risk: write

await corsair.grist.api.docs.move({ docId: 'doc123example', workspace: 2 });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`workspace`	`number`	Yes	—

Output: any

docs.pin Pin a document for quick access Risk: write

await corsair.grist.api.docs.pin({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: any

remove

docs.remove Move a document to the trash Risk: destructive

await corsair.grist.api.docs.remove({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: any

removeSnapshots

docs.removeSnapshots Remove historical snapshots of a document Risk: destructive

await corsair.grist.api.docs.removeSnapshots({ docId: 'doc123example', snapshotIds: ['snap123'] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`snapshotIds`	`string[]`	Yes	—

Output: any

unpin

docs.unpin Unpin a document Risk: write

await corsair.grist.api.docs.unpin({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: any

unremove

docs.unremove Restore a document from the trash Risk: write

await corsair.grist.api.docs.unremove({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output: any

update

docs.update Modify document metadata such as name or pin status Risk: write

await corsair.grist.api.docs.update({ docId: 'doc123example', name: 'Inventory 2026' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`name`	`string`	No	—
`isPinned`	`boolean`	No	—

Output: any

Orgs

delete

orgs.delete Delete an organization by ID and confirmed name Risk: destructive

await corsair.grist.api.orgs.delete({ orgId: 'current', name: 'My Team' });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—
`name`	`string`	Yes	—

Output: any

get

orgs.get Describe details of a specific organization Risk: read

await corsair.grist.api.orgs.get({ orgId: 'current' });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`name`	`string`	Yes	—
`domain`	`string \| null`	No	—
`owner`	`object \| null`	No	—
`access`	`owners \| editors \| viewers \| members \| guests \| string \| null`	No	—
`createdAt`	`string`	No	—
`updatedAt`	`string`	No	—

owner full type

{
  id: number,
  name: string,
  picture?: string | null,
  email?: string
} | null

getUsage

orgs.getUsage Get organization resource and storage usage summary Risk: read

await corsair.grist.api.orgs.getUsage({ orgId: 'current' });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—

Output: Record<string, any>

list

orgs.list List organizations accessible to the authenticated user Risk: read

await corsair.grist.api.orgs.list({});

Input: empty object Output: object[]

Output full type

{
  id: number,
  name: string,
  domain?: string | null,
  owner?: {
    id: number,
    name: string,
    picture?: string | null,
    email?: string
  } | null,
  access?: owners | editors | viewers | members | guests | string | null,
  createdAt?: string,
  updatedAt?: string
}[]

listAccess

orgs.listAccess List users with access permissions to an organization Risk: read

await corsair.grist.api.orgs.listAccess({ orgId: 'current' });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`users`	`object[]`	Yes	—

users full type

{
  id: number,
  name: string,
  email?: string,
  access?: owners | editors | viewers | members | guests | string | null
}[]

modifyAccess

orgs.modifyAccess Change user access roles for an organization; sharing with a new email address sends that person an invitation Risk: destructive

await corsair.grist.api.orgs.modifyAccess({ orgId: 'current', users: { 'user@example.com': 'editors' } });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—
`users`	`Record<string, owners \| editors \| viewers \| members \| null>`	Yes	—

Output: any

update

orgs.update Modify organization metadata such as its name Risk: write

await corsair.grist.api.orgs.update({ orgId: 'current', name: 'My Team' });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—
`name`	`string`	No	—

Output: any

Profile

get

profile.get Get current authenticated user profile Risk: read

await corsair.grist.api.profile.get({});

Input: empty object Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`name`	`string`	Yes	—
`picture`	`string \| null`	No	—
`email`	`string`	No	—

updateLocale

profile.updateLocale Update user locale preference Risk: write

await corsair.grist.api.profile.updateLocale({ locale: 'en-US' });

Input

Name	Type	Required	Description
`locale`	`string \| null`	No	—

Output: any

updateName

profile.updateName Update user display name Risk: write

await corsair.grist.api.profile.updateName({ name: 'Jane Doe' });

Input

Name	Type	Required	Description
`name`	`string`	Yes	—

Output: any

Records

add

records.add Add new records with field values to a table Risk: write

await corsair.grist.api.records.add({ docId: 'doc123example', tableId: 'Table1', records: [{ fields: { pet: 'cat', popularity: 67 } }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`noparse`	`boolean`	No	—
`records`	`object[]`	Yes	—

records full type

{
  fields: Record<string, any>
}[]

Output

Name	Type	Required	Description
`records`	`object[]`	Yes	—

records full type

{
  id: number
}[]

delete

records.delete Delete records by record IDs from a table Risk: destructive

await corsair.grist.api.records.delete({ docId: 'doc123example', tableId: 'Table1', recordIds: [1] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`recordIds`	`number[]`	Yes	—

Output: any

list

records.list Fetch records from a table with filtering and sorting Risk: read

await corsair.grist.api.records.list({ docId: 'doc123example', tableId: 'Table1' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`filter`	`string`	No	—
`sort`	`string`	No	—
`limit`	`number`	No	—
`hidden`	`boolean`	No	—
`cellFormat`	`normal \| typed`	No	—

Output

Name	Type	Required	Description
`records`	`object[]`	Yes	—

records full type

{
  id: number,
  fields: Record<string, any>,
  errors?: Record<string, any>
}[]

replace

records.replace Add or update records matching require criteria (upsert) Risk: write

await corsair.grist.api.records.replace({ docId: 'doc123example', tableId: 'Table1', records: [{ require: { pet: 'cat' }, fields: { popularity: 85 } }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`noparse`	`boolean`	No	—
`onmany`	`first \| none \| all`	No	—
`noadd`	`boolean`	No	—
`noupdate`	`boolean`	No	—
`allow_empty_require`	`boolean`	No	—
`records`	`object[]`	Yes	—

records full type

{
  require: Record<string, any>,
  fields?: Record<string, any>
}[]

Output: any

update

records.update Modify existing records by record ID in a table Risk: write

await corsair.grist.api.records.update({ docId: 'doc123example', tableId: 'Table1', records: [{ id: 1, fields: { popularity: 80 } }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tableId`	`string`	Yes	—
`noparse`	`boolean`	No	—
`records`	`object[]`	Yes	—

records full type

{
  id: number,
  fields: Record<string, any>
}[]

Output: any

Service Accounts

create

serviceAccounts.create Create a new service account with an API key Risk: write

await corsair.grist.api.serviceAccounts.create({ label: 'CI Service Account', expiresAt: '2027-01-01' });

Input

Name	Type	Required	Description
`label`	`string`	No	—
`description`	`string`	No	—
`expiresAt`	`string`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`login`	`string`	Yes	—
`label`	`string \| null`	No	—
`description`	`string \| null`	No	—
`expiresAt`	`string \| null`	No	—
`hasValidKey`	`boolean`	No	—
`key`	`string`	Yes	—

delete

serviceAccounts.delete Delete a service account Risk: destructive

await corsair.grist.api.serviceAccounts.delete({ saId: 1 });

Input

Name	Type	Required	Description
`saId`	`string \| number`	Yes	—

Output: any

deleteApiKey

serviceAccounts.deleteApiKey Delete a service account API key Risk: destructive

await corsair.grist.api.serviceAccounts.deleteApiKey({ saId: 1 });

Input

Name	Type	Required	Description
`saId`	`string \| number`	Yes	—

Output: any

get

serviceAccounts.get Get service account details by ID Risk: read

await corsair.grist.api.serviceAccounts.get({ saId: 1 });

Input

Name	Type	Required	Description
`saId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`login`	`string`	Yes	—
`label`	`string \| null`	No	—
`description`	`string \| null`	No	—
`expiresAt`	`string \| null`	No	—
`hasValidKey`	`boolean`	No	—

list

serviceAccounts.list List all service accounts owned by the user Risk: read

await corsair.grist.api.serviceAccounts.list({});

Input: empty object Output: object[]

Output full type

{
  id: number,
  login: string,
  label?: string | null,
  description?: string | null,
  expiresAt?: string | null,
  hasValidKey?: boolean
}[]

regenerateApiKey

serviceAccounts.regenerateApiKey Generate a new API key for a service account; the previous key stops working Risk: destructive

await corsair.grist.api.serviceAccounts.regenerateApiKey({ saId: 1 });

Input

Name	Type	Required	Description
`saId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`login`	`string`	Yes	—
`label`	`string \| null`	No	—
`description`	`string \| null`	No	—
`expiresAt`	`string \| null`	No	—
`hasValidKey`	`boolean`	No	—
`key`	`string`	Yes	—

update

serviceAccounts.update Modify service account name or label Risk: write

await corsair.grist.api.serviceAccounts.update({ saId: 1, label: 'Updated CI Service Account' });

Input

Name	Type	Required	Description
`saId`	`string \| number`	Yes	—
`label`	`string`	No	—
`description`	`string`	No	—
`expiresAt`	`string`	No	—

Output: any

Session

getActive

session.getActive Get active session details and current organization Risk: read

await corsair.grist.api.session.getActive({});

Input: empty object Output

Name	Type	Required	Description
`user`	`object`	No	—
`org`	`object \| null`	No	—
`orgError`	`any`	No	—

user full type

{
  id: number,
  name: string,
  picture?: string | null,
  email?: string
}

org full type

{
  id: number,
  name: string,
  domain?: string | null,
  owner?: {
    id: number,
    name: string,
    picture?: string | null,
    email?: string
  } | null,
  access?: owners | editors | viewers | members | guests | string | null,
  createdAt?: string,
  updatedAt?: string
} | null

getAll

session.getAll Get all logged-in session accounts and organizations Risk: read

await corsair.grist.api.session.getAll({});

Input: empty object Output

Name	Type	Required	Description
`users`	`object[]`	No	—
`orgs`	`object[]`	No	—

users full type

{
  id: number,
  name: string,
  picture?: string | null,
  email?: string
}[]

orgs full type

{
  id: number,
  name: string,
  domain?: string | null,
  owner?: {
    id: number,
    name: string,
    picture?: string | null,
    email?: string
  } | null,
  access?: owners | editors | viewers | members | guests | string | null,
  createdAt?: string,
  updatedAt?: string
}[]

Sql

query

sql.query Execute a read-only SQL query with parameters against a document Risk: read

await corsair.grist.api.sql.query({ docId: 'doc123example', sql: 'SELECT * FROM Table1 WHERE popularity >= ?', args: [50] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`sql`	`string`	Yes	—
`args`	`(string \| number \| boolean \| null)[]`	No	—
`timeout`	`number`	No	—

Output

Name	Type	Required	Description
`statement`	`string`	Yes	—
`records`	`object[]`	Yes	—

records full type

{
  fields: Record<string, any>
}[]

queryGet

sql.queryGet Execute a simple read-only SQL query via GET against a document Risk: read

await corsair.grist.api.sql.queryGet({ docId: 'doc123example', q: 'SELECT * FROM Table1' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`q`	`string`	Yes	—

Output

Name	Type	Required	Description
`statement`	`string`	No	—
`records`	`object[]`	Yes	—

records full type

{
  fields: Record<string, any>
}[]

Tables

create

tables.create Add new tables and their column definitions to a document Risk: write

await corsair.grist.api.tables.create({ docId: 'doc123example', tables: [{ id: 'Products', columns: [{ id: 'title', fields: { label: 'Title' } }] }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tables`	`object[]`	Yes	—

tables full type

{
  id?: string,
  columns: {
    id?: string,
    fields?: Record<string, any>
  }[]
}[]

Output

Name	Type	Required	Description
`tables`	`object[]`	Yes	—

tables full type

{
  id: string
}[]

list

tables.list List tables within a Grist document Risk: read

await corsair.grist.api.tables.list({ docId: 'doc123example' });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—

Output

Name	Type	Required	Description
`tables`	`object[]`	Yes	—

tables full type

{
  id: string,
  fields: {
    tableRef?: number,
    onDemand?: boolean
  }
}[]

update

tables.update Modify table identifiers or on-demand loading settings Risk: write

await corsair.grist.api.tables.update({ docId: 'doc123example', tables: [{ id: 'Products', fields: { tableId: 'Items' } }] });

Input

Name	Type	Required	Description
`docId`	`string`	Yes	—
`tables`	`object[]`	Yes	—

tables full type

{
  id: string,
  fields: {
    tableId?: string,
    onDemand?: boolean
  }
}[]

Output: any

Templates

get

templates.get Get details of a specific document template Risk: read

await corsair.grist.api.templates.get({ templateId: 1 });

Input

Name	Type	Required	Description
`templateId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`id`	`string`	Yes	—
`name`	`string`	Yes	—
`access`	`owners \| editors \| viewers \| members \| guests \| string \| null`	No	—
`isPinned`	`boolean`	No	—
`urlId`	`string \| null`	No	—
`workspace`	`object`	No	—

workspace full type

{
  id: number,
  name: string,
  access?: owners | editors | viewers | members | guests | string | null,
  org?: {
    id: number,
    name: string,
    domain?: string | null,
    owner?: {
      id: number,
      name: string,
      picture?: string | null,
      email?: string
    } | null,
    access?: owners | editors | viewers | members | guests | string | null,
    createdAt?: string,
    updatedAt?: string
  }
}

list

templates.list List available document templates from the catalog Risk: read

await corsair.grist.api.templates.list({});

Input: empty object Output: object[]

Output full type

{
  id: number,
  name: string,
  access?: owners | editors | viewers | members | guests | string | null,
  docs?: {
    id: string,
    name: string,
    access?: owners | editors | viewers | members | guests | string | null,
    isPinned?: boolean,
    urlId?: string | null
  }[],
  orgDomain?: string
}[]

Users

delete

users.delete Delete a user from Grist Risk: destructive

await corsair.grist.api.users.delete({ userId: 1, name: 'Jane Doe' });

Input

Name	Type	Required	Description
`userId`	`string \| number`	Yes	—
`name`	`string`	Yes	—

Output: any

disable

users.disable Disable a user account in Grist Risk: write

await corsair.grist.api.users.disable({ userId: 1 });

Input

Name	Type	Required	Description
`userId`	`string \| number`	Yes	—

Output: any

enable

users.enable Enable a previously disabled user account Risk: write

await corsair.grist.api.users.enable({ userId: 1 });

Input

Name	Type	Required	Description
`userId`	`string \| number`	Yes	—

Output: any

Widgets

list

widgets.list List available custom widgets from the gallery Risk: read

await corsair.grist.api.widgets.list({});

Input: empty object Output: object[]

Output full type

{
  name?: string,
  url?: string,
  widgetId?: string
}[]

Workspaces

create

workspaces.create Create a new empty workspace in an organization Risk: write

await corsair.grist.api.workspaces.create({ orgId: 'current', name: 'Operations' });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—
`name`	`string`	Yes	—

Output: number

delete

workspaces.delete Permanently delete a workspace Risk: destructive

await corsair.grist.api.workspaces.delete({ workspaceId: 1 });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—

Output: any

get

workspaces.get Describe a workspace and its documents Risk: read

await corsair.grist.api.workspaces.get({ workspaceId: 1 });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`id`	`number`	Yes	—
`name`	`string`	Yes	—
`access`	`owners \| editors \| viewers \| members \| guests \| string \| null`	No	—
`docs`	`object[]`	No	—

docs full type

{
  id: string,
  name: string,
  access?: owners | editors | viewers | members | guests | string | null,
  isPinned?: boolean,
  urlId?: string | null
}[]

list

workspaces.list List workspaces and their documents within an organization Risk: read

await corsair.grist.api.workspaces.list({ orgId: 'current' });

Input

Name	Type	Required	Description
`orgId`	`string \| number`	Yes	—

Output: object[]

Output full type

{
  id: number,
  name: string,
  access?: owners | editors | viewers | members | guests | string | null,
  docs?: {
    id: string,
    name: string,
    access?: owners | editors | viewers | members | guests | string | null,
    isPinned?: boolean,
    urlId?: string | null
  }[]
}[]

listAccess

workspaces.listAccess List users with access permissions to a workspace Risk: read

await corsair.grist.api.workspaces.listAccess({ workspaceId: 1 });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—

Output

Name	Type	Required	Description
`maxInheritedRole`	`owners \| editors \| viewers \| members \| guests \| string \| null`	No	—
`users`	`object[]`	Yes	—

users full type

{
  id: number,
  name: string,
  email?: string,
  access?: owners | editors | viewers | members | guests | string | null,
  parentAccess?: owners | editors | viewers | members | guests | string | null
}[]

modifyAccess

workspaces.modifyAccess Change user access permissions for a workspace; sharing with a new email address sends that person an invitation Risk: destructive

await corsair.grist.api.workspaces.modifyAccess({ workspaceId: 1, users: { 'user@example.com': 'viewers' } });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—
`maxInheritedRole`	`owners \| editors \| viewers \| null`	No	—
`users`	`Record<string, owners \| editors \| viewers \| members \| null>`	Yes	—

Output: any

remove

workspaces.remove Move a workspace to the trash Risk: destructive

await corsair.grist.api.workspaces.remove({ workspaceId: 1 });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—

Output: any

unremove

workspaces.unremove Restore a workspace from the trash Risk: write

await corsair.grist.api.workspaces.unremove({ workspaceId: 1 });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—

Output: any

update

workspaces.update Modify workspace name or settings Risk: write

await corsair.grist.api.workspaces.update({ workspaceId: 1, name: 'Operations Hub' });

Input

Name	Type	Required	Description
`workspaceId`	`string \| number`	Yes	—
`name`	`string`	Yes	—

Output: any