info:
  description: |
    An API for manipulating Grist sites, workspaces, and documents.

    # Authentication
    <SecurityDefinitions />
  version: "1.0.1"
  title: "Grist API"
openapi: 3.0.0
security:
  - ApiKey: []
servers:
  - url: https://{gristhost}/api
    variables:
        subdomain:
            description: The team name, or `docs` for personal areas
            default: docs

paths:
  /orgs:
    get:
      operationId: listOrgs
      tags:
        - orgs
      summary: "List the orgs you have access to"
      description: "This enumerates all the team sites or personal areas available."
      responses:
        200:
          description: An array of organizations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Orgs"
  /orgs/{orgId}:
    get:
      operationId: describeOrg
      tags:
        - orgs
      summary: "Describe an org"
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        200:
          description: An organization
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Org"
    patch:
      operationId: modifyOrg
      tags:
        - orgs
      summary: "Modify an org"
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
      requestBody:
        description: "the changes to make"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OrgParameters"
        required: true
      responses:
        200:
          description: Success

  /orgs/{orgId}/{name}:
    delete:
      operationId: deleteOrg
      tags:
        - orgs
      summary: "Delete an org"
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
        - in: path
          name: name
          schema:
            type: string
          description: The organization name
          required: true
      responses:
        200:
          description: Success
        403:
          description: Access denied
        404:
          description: Not found

  /orgs/{orgId}/access:
    get:
      operationId: listOrgAccess
      tags:
        - orgs
      summary: "List users with access to org"
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        200:
          description: "Users with access to org"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrgAccessRead"
    patch:
      operationId: modifyOrgAccess
      tags:
        - orgs
      summary: "Change who has access to org"
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
      requestBody:
        description: "the changes to make"
        content:
          application/json:
            schema:
              type: object
              required:
                - delta
              properties:
                delta:
                  $ref: "#/components/schemas/OrgAccessWrite"
        required: true
      responses:
        200:
          description: Success

  /orgs/{orgId}/usage:
    get:
      operationId: getOrgUsage
      tags:
        - orgs
      summary: "Get organization usage summary"
      description: |
        Get usage statistics for all non-deleted documents in the organization.
        Only accessible to organization owners.
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        200:
          description: "Usage summary"
          content:
            application/json:
              schema:
                type: object
                properties:
                  countsByDataLimitStatus:
                    type: object
                    description: "Count of documents grouped by data limit status"
                    properties:
                      approachingLimit:
                        type: integer
                      gracePeriod:
                        type: integer
                      deleteOnly:
                        type: integer
                  attachments:
                    type: object
                    required:
                      - totalBytes
                    properties:
                      totalBytes:
                        type: integer
                        description: "Total attachment storage used in bytes"
                      limitExceeded:
                        type: boolean
                        description: "Whether the attachment limit has been exceeded (only present when limit is exceeded)"

  /orgs/{orgId}/workspaces:
    get:
      operationId: listWorkspaces
      tags:
        - workspaces
      summary: "List workspaces and documents within an org"
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        200:
          description: An org's workspaces and documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkspaceWithDocsAndDomain"
    post:
      operationId: createWorkspace
      tags:
        - workspaces
      summary: "Create an empty workspace"
      parameters:
        - $ref: '#/components/parameters/orgIdPathParam'
      requestBody:
        description: "settings for the workspace"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkspaceParameters"
        required: true
      responses:
        200:
          description: The workspace id
          content:
            application/json:
              schema:
                type: integer
                description: an identifier for the workspace
                example: 155



  /workspaces/{workspaceId}:
    get:
      operationId: describeWorkspace
      tags:
        - workspaces
      summary: "Describe a workspace"
      parameters:
        - $ref: '#/components/parameters/workspaceIdPathParam'
      responses:
        200:
          description: A workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceWithDocsAndOrg"
    patch:
      operationId: modifyWorkspace
      tags:
        - workspaces
      summary: "Modify a workspace"
      parameters:
        - $ref: '#/components/parameters/workspaceIdPathParam'
      requestBody:
        description: "the changes to make"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkspaceParameters"
        required: true
      responses:
        200:
          description: Success
    delete:
      operationId: deleteWorkspace
      tags:
        - workspaces
      summary: "Delete a workspace"
      parameters:
        - $ref: '#/components/parameters/workspaceIdPathParam'
      responses:
        200:
          description: Success

  /workspaces/{workspaceId}/remove:
    post:
      operationId: removeWorkspace
      tags:
        - workspaces
      summary: "Move workspace to trash"
      description: |
        Soft-delete the workspace by moving it to trash. The workspace can be
        restored using the unremove endpoint. If the `permanent` query parameter
        is set to true, the workspace is permanently deleted instead.
      parameters:
        - $ref: '#/components/parameters/workspaceIdPathParam'
        - in: query
          name: permanent
          schema:
            type: boolean
          description: "If true, permanently delete instead of moving to trash"
      responses:
        200:
          description: Workspace moved to trash (or permanently deleted)

  /workspaces/{workspaceId}/unremove:
    post:
      operationId: unremoveWorkspace
      tags:
        - workspaces
      summary: "Restore workspace from trash"
      description: |
        Recover a workspace that was previously soft-deleted. Only works if the
        workspace is still in the trash.
      parameters:
        - $ref: '#/components/parameters/workspaceIdPathParam'
      responses:
        200:
          description: Workspace restored successfully

  /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"

  /workspaces/{workspaceId}/access:
    get:
      operationId: listWorkspaceAccess
      tags:
        - workspaces
      summary: "List users with access to workspace"
      parameters:
        - $ref: '#/components/parameters/workspaceIdPathParam'
      responses:
        200:
          description: "Users with access to workspace"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAccessRead"
    patch:
      operationId: modifyWorkspaceAccess
      tags:
        - workspaces
      summary: "Change who has access to workspace"
      parameters:
        - $ref: '#/components/parameters/workspaceIdPathParam'
      requestBody:
        description: "the changes to make"
        content:
          application/json:
            schema:
              type: object
              required:
                - delta
              properties:
                delta:
                  $ref: "#/components/schemas/WorkspaceAccessWrite"
        required: true
      responses:
        200:
          description: Success

  /templates:
    get:
      operationId: listTemplates
      tags:
        - templates
      summary: "List available templates"
      description: |
        Get all available templates. Templates are organized by workspace within
        a template organization configured on the server.

        **Note:** Requires a template organization to be configured on the server.
      responses:
        200:
          description: "List of workspaces containing templates"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WorkspaceWithDocsAndDomain"

  /templates/{templateId}:
    get:
      operationId: getTemplate
      tags:
        - templates
      summary: "Get template details"
      description: |
        Get information about a specific template.

        **Note:** Requires a template organization to be configured on the server.
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
          description: "ID of the template"
      responses:
        200:
          description: "Template information"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocWithWorkspace"

  /widgets:
    get:
      operationId: listWidgets
      tags:
        - widgets
      summary: "List available custom widgets"
      description: |
        Get all widget definitions from the configured widget repository.
        Custom widgets extend Grist's functionality with specialized views.
      responses:
        200:
          description: "List of widgets"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: "Widget display name"
                    url:
                      type: string
                      description: "URL to load the widget"
                    widgetId:
                      type: string
                      description: "Unique widget identifier"

  /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:
          description: Document content replaced successfully

  /docs/{docId}/recover:
    post:
      operationId: recoverDoc
      tags:
        - docs
      summary: "Set recovery mode for a document"
      description: "Controls the recovery mode of a document. Recovery mode helps in recovering from errors or corrupted states. Only document owners can control recovery mode."
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: "Recovery mode settings"
        content:
          application/json:
            schema:
              type: object
              properties:
                recoveryMode:
                  type: boolean
                  description: "Whether to enable recovery mode. Defaults to true if not specified."
                  example: true
        required: false
      responses:
        200:
          description: Recovery mode set successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - recoveryMode
                properties:
                  recoveryMode:
                    type: boolean
                    description: "The current recovery mode state of the document"
                    example: true
        403:
          description: Access denied - only owners can control recovery mode
        404:
          description: Document not found

  /docs/{docId}/timing:
    get:
      operationId: getTimingStatus
      tags:
        - docs
      summary: "Get formula timing status"
      description: |
        Check if formula timing is enabled for a document and retrieve timing data
        if available. Only document owners can access timing information.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: "Timing status"
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    type: string
                    enum: ["disabled", "pending", "active"]
                    description: |
                      - disabled: timing is not enabled
                      - pending: timing is enabled but no data yet
                      - active: timing is enabled and data is available
                  timing:
                    type: object
                    description: "Timing data (only present when status is 'active')"

  /docs/{docId}/timing/start:
    post:
      operationId: startTiming
      tags:
        - docs
      summary: "Start formula timing"
      description: |
        Start collecting timing information for formula calculations.
        Only document owners can start timing.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Timing started successfully
        400:
          description: Timing already started for this document

  /docs/{docId}/timing/stop:
    post:
      operationId: stopTiming
      tags:
        - docs
      summary: "Stop formula timing"
      description: |
        Stop collecting timing information and return the collected data.
        Only document owners can stop timing.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: "Timing stopped and data returned"
          content:
            application/json:
              schema:
                type: object
                description: "Collected timing data for formulas"
        400:
          description: Timing not started for this document

  /docs/{docId}/apply:
    post:
      operationId: applyUserActions
      tags:
        - docs
      summary: "Apply a list of user actions"
      description: |
        Apply a sequence of user actions to a document. This is a low-level endpoint
        for making batch changes using Grist's internal action format.

        Each action is an array where the first element is the action type.
        Common action types:
        - `["AddRecord", tableId, rowId, {column: value}]` - Add a row (use null for auto-assigned rowId)
        - `["UpdateRecord", tableId, rowId, {column: value}]` - Update a row
        - `["RemoveRecord", tableId, rowId]` - Delete a row
        - `["BulkAddRecord", tableId, [rowIds], {column: [values]}]` - Add multiple rows
        - `["BulkUpdateRecord", tableId, [rowIds], {column: [values]}]` - Update multiple rows
        - `["BulkRemoveRecord", tableId, [rowIds]]` - Delete multiple rows
        - `["AddColumn", tableId, colId, {type, ...}]` - Add a column
        - `["RemoveColumn", tableId, colId]` - Remove a column
        - `["RenameColumn", tableId, oldColId, newColId]` - Rename a column
        - `["AddTable", tableId, [{id, type, ...}]]` - Add a table
        - `["RemoveTable", tableId]` - Remove a table
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: query
          name: noparse
          schema:
            type: boolean
          description: "If true, string values are stored as-is without parsing (e.g. dates won't be auto-converted)"
      requestBody:
        description: "An array of user actions to apply"
        content:
          application/json:
            schema:
              type: array
              items:
                type: array
                description: "A user action: [actionType, ...args]"
              example:
                - ["AddRecord", "People", null, {"Name": "Alice", "Age": 30}]
                - ["UpdateRecord", "People", 1, {"Age": 31}]
        required: true
      responses:
        200:
          description: Actions applied successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  actionNum:
                    type: integer
                    description: "The action number assigned"
                  retValues:
                    type: array
                    description: "Return values from each action (e.g. new row IDs)"

  /docs/{docId}/tables/{tableId}/data:
    get:
      operationId: getTableData
      tags:
        - data
      summary: "Fetch data from a table"
      deprecated: true
      description: "Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects."
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/sortQueryParam'
        - $ref: '#/components/parameters/limitQueryParam'
        - $ref: '#/components/parameters/sortHeaderParam'
        - $ref: '#/components/parameters/limitHeaderParam'
      responses:
        200:
          description: Cells from the table
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Data"
    post:
      operationId: addRows
      tags:
        - data
      summary: "Add rows to a table"
      deprecated: true
      description: "Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects."
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/noparseQueryParam'
      requestBody:
        description: "the data to add"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DataWithoutId"
        required: true
      responses:
        200:
          description: IDs of rows added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RowIds"
    patch:
      operationId: modifyRows
      tags:
        - data
      summary: "Modify rows of a table"
      deprecated: true
      description: "Deprecated in favor of `records` endpoints. We have no immediate plans to remove these endpoints, but consider `records` a better starting point for new projects."
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/noparseQueryParam'
      requestBody:
        description: "the data to change, with ids"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Data"
        required: true
      responses:
        200:
          description: IDs of rows modified
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RowIds"
  /docs/{docId}/tables/{tableId}/data/delete:
    post:
      operationId: deleteRows
      tags:
        - data
      summary: "Delete rows of a table"
      deprecated: true
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
      requestBody:
        description: "the IDs of rows to remove"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RowIds"
        required: true
      responses:
        200:
          description: Nothing returned
  /docs/{docId}/attachments:
    get:
      operationId: "listAttachments"
      tags:
        - attachments
      summary: "List metadata of all attachments in a doc"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/sortQueryParam'
        - $ref: '#/components/parameters/limitQueryParam'
        - $ref: '#/components/parameters/sortHeaderParam'
        - $ref: '#/components/parameters/limitHeaderParam'
      responses:
        200:
          description: List of attachment metadata records. Note that the list may temporarily include records for attachments that are stored in the document but not referenced by any Attachments type cell.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentMetadataList"
    post:
      operationId: "uploadAttachments"
      tags:
        - attachments
      summary: "Upload attachments to a doc"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: "the files to add to the doc"
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/AttachmentUpload"
        required: true
      responses:
        200:
          description: IDs of attachments added, one per file.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RowIds"
  /docs/{docId}/attachments/{attachmentId}:
    get:
      operationId: "getAttachmentMetadata"
      tags:
        - attachments
      summary: "Get the metadata for an attachment"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: path
          name: attachmentId
          schema:
            $ref: '#/components/schemas/AttachmentId'
          required: true
      responses:
        200:
          description: Attachment metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentMetadata"
  /docs/{docId}/attachments/{attachmentId}/download:
    get:
      operationId: "downloadAttachment"
      tags:
        - attachments
      summary: "Download the contents of an attachment"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: path
          name: attachmentId
          schema:
            $ref: '#/components/schemas/AttachmentId'
          required: true
      responses:
        200:
          description: Attachment contents, with suitable Content-Type.
  /docs/{docId}/attachments/archive:
    get:
      operationId: downloadAttachments
      tags:
        - attachments
      summary: "Download all attachments"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: query
          name: format
          schema:
            type: string
            enum: ['zip', 'tar']
      responses:
        200:
          description: Archive of all attachments, in either .zip or .tar format.
    post:
      operationId: uploadMissingAttachments
      tags:
        - attachments
      summary: "Upload missing attachments"
      description: "Restores attachments which are missing from external storage."
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: "A .tar file downloaded from Grist, containing all the document's attachments."
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: "The .tar file. Must have `Content-Type=application/x-tar` set."
      responses:
        200:
          description: Summary of attachments used
          content:
            application/json:
              schema:
                type: object
                properties:
                  added:
                    type: integer
                    description: "Total files added to external storage."
                  errored:
                    type: integer
                    description: "Total files that errored when attempting to process them."
                  unused:
                    type: integer
                    description: "Total files that aren't needed, or don't match an existing attachment."

  /docs/{docId}/attachments/store:
    get:
      operationId: getDocumentAttachmentStore
      tags:
        - attachments
      summary: "Get external store"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document's current external storage setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentStoreSetting'
    post:
      operationId: setDocumentAttachmentStore
      tags:
        - attachments
      summary: "Set external store"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentStoreSetting'
      responses:
        200:
          description: The ID of the store the document's store
          content:
            application/json:
              schema:
                type: object
                properties:
                  store:
                    $ref: '#/components/schemas/DocumentStoreId'

  /docs/{docId}/attachments/stores:
    get:
      operationId: listAttachmentStores
      tags:
        - attachments
      summary: "List external attachment stores"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document's current external storage setting
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentStoreSetting'

  /docs/{docId}/attachments/transferAll:
    post:
      operationId: startAttachmentTransfer
      tags:
        - attachments
      summary: "Start transferring attachments"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Transfer status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsTransferStatus'

  /docs/{docId}/attachments/transferStatus:
    get:
      operationId: getAttachmentTransferStatus
      tags:
        - attachments
      summary: "Get attachment transfer status"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Transfer status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentsTransferStatus'


  /docs/{docId}/attachments/removeUnused:
    post:
      operationId: removeUnusedAttachments
      tags:
        - attachments
      summary: "Delete unused attachments from the document"
      description: >
        When an uploaded attachment is no longer used in a Grist document, 
        it's retained for a period of time in case it's needed again (e.g. to facilitate an "undo").
        
        This removes all of these retained attachments, reducing the amount of storage used.
        This is particularly useful if a document has hit its attachment storage limit.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: query
          name: expiredOnly
          schema:
            type: boolean
            description: "Only remove attachments that haven't been used for a period of time. This duration is set by host of the Grist instance."
      responses:
        200:
          description: Success

  /docs/{docId}/attachments/updateUsed:
    post:
      operationId: updateUsedAttachments
      tags:
        - attachments
      summary: "Update attachment usage tracking"
      description: |
        Recalculate which attachments are in use by scanning the document.
        This is mostly used for testing and maintenance.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Success

  /docs/{docId}/attachments/verifyFiles:
    post:
      operationId: verifyAttachmentFiles
      tags:
        - attachments
      summary: "Verify attachment file integrity"
      description: |
        Verify that attachment records match the actual stored files.
        This is a maintenance endpoint to check for data consistency.
        Only document owners can call this endpoint.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Verification passed

  /docs/{docId}/tables/{tableId}/records:
    get:
      operationId: "listRecords"
      tags:
        - records
      summary: "Fetch records from a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/sortQueryParam'
        - $ref: '#/components/parameters/limitQueryParam'
        - $ref: '#/components/parameters/sortHeaderParam'
        - $ref: '#/components/parameters/limitHeaderParam'
        - $ref: '#/components/parameters/hiddenQueryParam'
      responses:
        200:
          description: Records from the table
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecordsList"
    post:
      operationId: "addRecords"
      tags:
        - records
      summary: "Add records to a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/noparseQueryParam'
      requestBody:
        description: "the records to add"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecordsWithoutId"
        required: true
      responses:
        200:
          description: IDs of records added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecordsWithoutFields"
    patch:
      operationId: "modifyRecords"
      tags:
        - records
      summary: "Modify records of a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/noparseQueryParam'
      requestBody:
        description: "the records to change, with ids"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecordsList"
        required: true
      responses:
        200:
          description: Success
    put:
      operationId: "replaceRecords"
      tags:
        - records
      summary: "Add or update records of a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/noparseQueryParam'
        - in: query
          name: onmany
          schema:
            type: string
            enum:
              - first
              - none
              - all
            description: >
              Which records to update if multiple records are found to match `require`.
                * `first` - the first matching record (default)
                * `none` - do not update anything
                * `all` - update all matches
        - in: query
          name: noadd
          schema:
            type: boolean
            description: "Set to true to prohibit adding records."
        - in: query
          name: noupdate
          schema:
            type: boolean
            description: "Set to true to prohibit updating records."
        - in: query
          name: allow_empty_require
          schema:
            type: boolean
            description: "Set to true to allow `require` in the body to be empty, which will match and update all records in the table."
      requestBody:
        description: >
          The records to add or update. Instead of an id,
          a `require` object is provided, with the same structure as
          `fields`. If no query parameter options are set, then the operation
          is as follows. First, we check if a record exists matching
          the values specified for columns in `require`. If so, we update
          it by setting the values specified for columns in `fields`. If
          not, we create a new record with a combination of the values
          in `require` and `fields`, with `fields` taking priority if
          the same column is specified in both.
          The query parameters allow for variations on this behavior.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecordsWithRequire"
        required: true
      responses:
        200:
          description: Success

  /docs/{docId}/tables/{tableId}/records/delete:
    post:
      operationId: deleteRecords
      tags:
        - records
      summary: "Delete records of a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
      requestBody:
        description: "the IDs of records to remove"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RowIds"
        required: true
      responses:
        200:
          description: Nothing returned

  /docs/{docId}/tables:
    get:
      operationId: "listTables"
      tags:
        - tables
      summary: "List tables in a document"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: The tables in a document
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TablesList"
    post:
      operationId: "addTables"
      tags:
        - tables
      summary: "Add tables to a document"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: "the tables to add"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTables"
        required: true
      responses:
        200:
          description: The table created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TablesWithoutFields"
    patch:
      operationId: "modifyTables"
      tags:
        - tables
      summary: "Modify tables of a document"
      description: |
        Modify metadata for existing tables. This endpoint is primarily useful for:
        - Renaming tables (via the `tableId` field)
        - Setting on-demand loading (via the `onDemand` field)
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: "the tables to modify, identified by their current id"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTables"
        required: true
      responses:
        200:
          description: Success

  /docs/{docId}/tables/{tableId}/columns:
    get:
      operationId: "listColumns"
      tags:
        - columns
      summary: "List columns in a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/hiddenQueryParam'
      responses:
        200:
          description: The columns in a table
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ColumnsList"
    post:
      operationId: "addColumns"
      tags:
        - columns
      summary: "Add columns to a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
      requestBody:
        description: "the columns to add"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateColumns"
        required: true
      responses:
        200:
          description: The columns created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ColumnsWithoutFields"
    patch:
      operationId: "modifyColumns"
      tags:
        - columns
      summary: "Modify columns of a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
      requestBody:
        description: "the columns to change, with ids"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateColumns"
        required: true
      responses:
        200:
          description: Success
    put:
      operationId: "replaceColumns"
      tags:
        - columns
      summary: "Add or update columns of a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - in: query
          name: noadd
          schema:
            type: boolean
            description: "Set to true to prohibit adding columns."
        - in: query
          name: noupdate
          schema:
            type: boolean
            description: "Set to true to prohibit updating columns."
        - in: query
          name: replaceall
          schema:
            type: boolean
            description: "Set to true to remove existing columns (except the hidden ones) that are not specified in the request body."
      requestBody:
        description: >
          The columns to add or update. We check whether the specified column ID exists:
          if so, the column is updated with the provided data, otherwise a new column is created.

          Also note that some query parameters alter this behavior.
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateColumns"
        required: true
      responses:
        200:
          description: Success
  /docs/{docId}/tables/{tableId}/columns/{colId}:
    delete:
      operationId: "deleteColumn"
      tags:
        - columns
      summary: "Delete a column of a table"
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - $ref: '#/components/parameters/tableIdPathParam'
        - $ref: '#/components/parameters/colIdPathParam'
      responses:
        200:
          description: Success

  /docs/{docId}/forms/{viewSectionId}:
    get:
      operationId: getFormData
      tags:
        - forms
      summary: "Get form view data"
      description: |
        Get the form configuration for a specific view section. Forms are
        a special view type that allows external users to submit data.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - name: viewSectionId
          in: path
          required: true
          schema:
            type: integer
          description: "ID of the view section (form)"
      responses:
        200:
          description: "Form data"
          content:
            application/json:
              schema:
                type: object
                properties:
                  formFieldsById:
                    type: object
                    description: "Form fields indexed by field ID"
                  formLayoutSpec:
                    type: string
                    description: "JSON layout specification for the form"
                  formTableId:
                    type: string
                    description: "ID of the table the form submits to"
                  formTitle:
                    type: string
                    description: "Title of the form"
        404:
          description: Form not found

  /docs/{docId}/webhooks:
    get:
      operationId: listWebhooks
      tags:
        - webhooks
      summary: "Webhooks associated with a document"
      description: |
        Returns all webhooks configured for this document, including their
        settings and delivery statistics.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: "A list of webhooks."
          content:
            application/json:
              schema:
                type: object
                required:
                  - webhooks
                properties:
                  webhooks:
                    $ref: "#/components/schemas/Webhooks"
    post:
      operationId: createWebhooks
      tags:
        - webhooks
      summary: "Create new webhooks for a document"
      description: |
        Creates one or more webhooks that will POST to specified URLs when
        data in the document changes. Returns the IDs of the created webhooks.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: "an array of webhook settings"
        content:
          application/json:
            schema:
              type: object
              required:
                - webhooks
              properties:
                webhooks:
                  type: array
                  items:
                    type: object
                    required:
                      - fields
                    properties:
                      fields:
                        $ref: "#/components/schemas/WebhookPartialFields"
      responses:
        200:
          description: "Success"
          content:
            application/json:
              schema:
                type: object
                required:
                  - webhooks
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: "#/components/schemas/WebhookId"

  /docs/{docId}/webhooks/{webhookId}:
    patch:
      operationId: modifyWebhook
      tags:
        - webhooks
      summary: "Modify a webhook"
      description: |
        Update the configuration of an existing webhook, such as its URL,
        enabled state, or event types.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: path
          name: webhookId
          schema:
            type: string
          required: true
      requestBody:
        description: "the changes to make"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookPartialFields"
      responses:
        200:
          description: "Webhook updated successfully. Returns empty body."
    delete:
      operationId: deleteWebhook
      tags:
        - webhooks
      summary: "Remove a webhook"
      description: |
        Permanently delete a webhook. Any pending deliveries in the queue
        for this webhook will also be removed.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: path
          name: webhookId
          schema:
            type: string
          required: true
      responses:
        200:
          description: "Webhook deleted successfully."
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                properties:
                  success:
                    type: boolean
                    example: true

  /docs/{docId}/webhooks/queue:
    delete:
      operationId: clearWebhookQueue
      tags:
        - webhooks
      summary: "Empty a document's queue of undelivered payloads"
      description: |
        Clear all pending webhook deliveries for this document. Use this
        if the queue has built up due to unreachable endpoints.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: "Queue cleared successfully. Returns empty body."

  /docs/{docId}/webhooks/queue/{webhookId}:
    delete:
      operationId: clearWebhookQueueForWebhook
      tags:
        - webhooks
      summary: "Clear queue for a specific webhook"
      description: |
        Clear the queue of pending payloads for a specific webhook.
        Only document owners can call this endpoint.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - name: webhookId
          in: path
          required: true
          schema:
            type: string
          description: "ID of the webhook"
      responses:
        200:
          description: "Queue cleared"
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true

  /docs/{docId}/sql:
    get:
      operationId: runSqlGet
      tags:
        - sql
      summary: "Run an SQL query against a document"
      description: |
        Execute a read-only SQL SELECT query against the document's SQLite database.
        This is a simplified endpoint for basic queries. For queries with parameters
        or custom timeouts, use the POST endpoint instead.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
        - in: query
          name: q
          schema:
            type: string
            description: "The SQL query to run. This GET endpoint is a simplified version of the corresponding POST endpoint, without support for parameters or options. See the POST endpoint for details of what's allowed in the SQL query string."
      responses:
        200:
          description: "The result set for the query."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SqlResultSet"
    post:
      operationId: runSql
      tags:
        - sql
      summary: "Run an SQL query against a document, with options or parameters"
      description: |
        Execute a read-only SQL SELECT query with support for parameterized queries
        and custom timeouts. All Grist documents are SQLite databases, and queries
        are executed directly against SQLite with security restrictions.
      parameters:
        - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: "Query options"
        content:
          application/json:
            schema:
              type: object
              required:
                - sql
              properties:
                sql:
                  type: string
                  description: "The SQL query to run. Must be a single SELECT statement, with no trailing semicolon. WITH clauses are permitted. All Grist documents are currently SQLite databases, and the SQL query is interpreted and run by SQLite, with various defensive measures. Statements that would modify the database are not supported."
                  example: "select * from Pets where popularity >= ?"
                args:
                  type: array
                  items:
                    oneOf:
                      - type: number
                      - type: string
                  description: "Parameters for the query."
                  example: [ 50 ]
                timeout:
                  type: number
                  description: "Timeout after which operations on the document will be interrupted. Specified in milliseconds. Defaults to 1000 (1 second). This default is controlled by an optional environment variable read by the Grist app, GRIST_SQL_TIMEOUT_MSEC. The default cannot be exceeded, only reduced."
                  example: 500
      responses:
        200:
          description: "The result set for the query."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SqlResultSet"

  /profile/user:
    get:
      operationId: getProfile
      tags:
        - profile
      summary: "Get current user's profile"
      description: "Returns the profile information of the currently authenticated user."
      responses:
        200:
          description: "User profile"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

  /profile/user/name:
    post:
      operationId: updateUserName
      tags:
        - profile
      summary: "Update user's name"
      description: "Update the display name for the current user."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: "New display name"
                  example: "John Doe"
      responses:
        200:
          description: Name updated successfully

  /profile/user/locale:
    post:
      operationId: updateUserLocale
      tags:
        - profile
      summary: "Update user's locale"
      description: "Update the locale preference for the current user."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  description: "Locale code (e.g. 'en-US', 'fr'). Set to null to clear."
                  example: "en-US"
      responses:
        200:
          description: Locale updated successfully

  /profile/apikey:
    get:
      operationId: getApiKey
      tags:
        - profile
      summary: "Get user's API key"
      description: "Returns the current user's API key if one exists."
      responses:
        200:
          description: "API key"
          content:
            text/plain:
              schema:
                type: string
    post:
      operationId: createApiKey
      tags:
        - profile
      summary: "Create or regenerate API key"
      description: "Create a new API key or regenerate an existing one."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                force:
                  type: boolean
                  description: "If true, regenerate even if a key already exists"
      responses:
        200:
          description: "New API key"
          content:
            text/plain:
              schema:
                type: string
    delete:
      operationId: deleteApiKey
      tags:
        - profile
      summary: "Delete user's API key"
      description: "Delete the current user's API key."
      responses:
        200:
          description: API key deleted successfully

  /session/access/active:
    get:
      operationId: getActiveSession
      tags:
        - session
      summary: "Get active session information"
      description: |
        Returns information about the active user and organization for the current session.
      responses:
        200:
          description: "Active session info"
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: "#/components/schemas/User"
                  org:
                    $ref: "#/components/schemas/Org"
                  orgError:
                    type: object
                    description: "Error information if org access failed"
                    properties:
                      error:
                        type: string
                      status:
                        type: integer
    post:
      operationId: setActiveUser
      tags:
        - session
      summary: "Set active user for organization"
      description: |
        Switch which user account is active for a given organization.
        Useful when a user has multiple accounts logged in.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  description: "Email of the user to make active"
                org:
                  type: string
                  description: "Organization subdomain or 'current'"
      responses:
        200:
          description: "Active user changed"
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
        403:
          description: Email not available for this session

  /session/access/all:
    get:
      operationId: getAllSessions
      tags:
        - session
      summary: "Get all session users and organizations"
      description: |
        Returns all user profiles logged into the current session and all
        organizations they can access.
      responses:
        200:
          description: "All session info"
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
                  orgs:
                    type: array
                    items:
                      $ref: "#/components/schemas/Org"

  /users/{userId}:
    delete:
      operationId: deleteUser
      tags:
        - users
      summary: "Delete a user from Grist"
      description: |
        This action also deletes the user's personal organisation and all the workspaces and documents it contains.
        Currently, only the users themselves are allowed to delete their own accounts.

        ⚠️ **This action cannot be undone, please be cautious when using this endpoint** ⚠️
      parameters:
        - $ref: '#/components/parameters/userIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: "The user's name to delete (for confirmation, to avoid deleting the wrong account)."
                  example: "John Doe"
      responses:
        200:
          description: "The account has been deleted successfully"
        400:
          description: "The passed user name does not match the one retrieved from the database given the passed user id"
        403:
          description: "The caller is not allowed to delete this account"
        404:
          description: "The user is not found"
  /users/{userId}/disable:
    post:
      operationId: disableUser
      tags:
        - users
      summary: "Disable a user"
      description: |
        A disabled user can not log in and loses access to all pages,
        including public ones, as well as API access. The operation is
        non-destructive. Disabled users can be re-enabled.

        Only admin accounts can disable a user.
      parameters:
        - $ref: '#/components/parameters/userIdPathParam'
      responses:
        200:
          description: "The account has been disabled successfully"
        403:
          description: "The caller is not allowed to disable this account"
        404:
          description: "The user is not found"
  /users/{userId}/enable:
    post:
      operationId: enableUser
      tags:
        - users
      summary: "Enable a user"
      description: |
        If a user has been disabled, this will restore their access, including API access.

        Only admin accounts can enable a user.
      parameters:
        - $ref: '#/components/parameters/userIdPathParam'
      responses:
        200:
          description: "The account has been enabled successfully"
        403:
          description: "The caller is not allowed to enable this account"
        404:
          description: "The user is not found"
  /service-accounts:
    get:
      operationId: listServiceAccounts
      tags:
        - service accounts
      summary: "Get all your service accounts"
      description: |
        This lists all your service accounts with their details.
      responses:
        200:
          description: "Array of your service accounts"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAccountsResult"
        403:
          description: "The caller is not allowed to access this resource"
    post:
      operationId: createServiceAccount
      tags:
        - service accounts
      summary: "Create a service account"
      description: |
        This creates a new service account with a new API key.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateServiceAccount"
      responses:
        200:
          description: "The service account created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAccountResultWithApiKey"
        403:
          description: "The caller is not allowed to create service accounts"
  /service-accounts/{saId}:
    get:
      operationId: getServiceAccount
      tags:
        - service accounts
      summary: "Get a service account's details"
      parameters:
        - $ref: '#/components/parameters/saIdPathParam'
      description: |
        This reports the details of a service account.
      responses:
        200:
          description: "Details of the service account"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAccountResult"
        403:
          description: Access denied
        404:
          description: "Service account not found"
    patch:
      operationId: modifyServiceAccount
      tags:
        - service accounts
      summary: "Modify a service account"
      parameters:
        - $ref: '#/components/parameters/saIdPathParam'
      description: |
        This updates a service account's label, description or expiration date.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ServiceAccountBody"
      responses:
        200:
          description: "Success (empty body)"
        403:
          description: "The caller is not allowed to modify this service account"
        404:
          description: "Service account not found"
    delete:
      operationId: deleteServiceAccount
      tags:
        - service accounts
      summary: "Delete a service account"
      parameters:
        - $ref: '#/components/parameters/saIdPathParam'
      description: |
        This deletes a given service account.
      responses:
        200:
          description: "Service account deleted successfully. Returns empty body."
        403:
          description: "The caller is not allowed to delete this service account"
        404:
          description: "Service account not found"
  /service-accounts/{saId}/apikey:
    post:
      operationId: regenerateServiceAccountApiKey
      tags:
        - service accounts
      summary: "Generate a new service account's api key"
      parameters:
        - $ref: '#/components/parameters/saIdPathParam'
      description: |
        This renews an api key of a given service account.
        Useful especially to change the API key when it has been leaked.
      responses:
        200:
          description: "The service account with the new API key"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAccountResultWithApiKey"
        403:
          description: "The caller is not allowed to regenerate this api key"
        404:
          description: "Service account not found"
    delete:
      operationId: deleteServiceAccountApiKey
      tags:
        - service accounts
      summary: "Delete a service account's api key"
      description: |
        Deletes the API key for a service account. The service account will
        no longer be able to authenticate until a new key is generated.
      parameters:
        - $ref: '#/components/parameters/saIdPathParam'
      responses:
        200:
          description: "API key deleted successfully. Returns empty body."
        403:
          description: "The caller is not allowed to delete this api key"
        404:
          description: "Service account not found"
  /scim/v2/Users:
    $ref: "./scim/users.yml#/paths/~1scim~1v2~1Users"
  /scim/v2/Users/{userId}:
    $ref: "./scim/users.yml#/paths/~1scim~1v2~1Users~1{userId}"
  /scim/v2/Users/.search:
    $ref: "./scim/users.yml#/paths/~1scim~1v2~1Users~1.search"
  /scim/v2/Me:
    $ref: "./scim/users.yml#/paths/~1scim~1v2~1Me"
  /scim/v2/Bulk:
    $ref: "./scim/bulk.yml#/paths/~1scim~1v2~1Bulk"
  /scim/v2/Schemas:
    $ref: "./scim/serviceproviderconfig.yml#/paths/~1scim~1v2~1Schemas"
  /scim/v2/ServiceProviderConfig:
    $ref: "./scim/serviceproviderconfig.yml#/paths/~1scim~1v2~1ServiceProviderConfig"
  /scim/v2/ResourceTypes:
    $ref: "./scim/serviceproviderconfig.yml#/paths/~1scim~1v2~1ResourceTypes"
  /scim/v2/Groups:
    $ref: "./scim/groups.yml#/paths/~1scim~1v2~1Groups"
  /scim/v2/Groups/{groupId}:
    $ref: "./scim/groups.yml#/paths/~1scim~1v2~1Groups~1{groupId}"
  /scim/v2/Groups/.search:
    $ref: "./scim/groups.yml#/paths/~1scim~1v2~1Groups~1.search"
  /scim/v2/Roles:
    $ref: "./scim/roles.yml#/paths/~1scim~1v2~1Roles"
  /scim/v2/Roles/{roleId}:
    $ref: "./scim/roles.yml#/paths/~1scim~1v2~1Roles~1{roleId}"

tags:
  - name: orgs
    description: "Team sites and personal spaces are called 'orgs' in the API."
  - name: workspaces
    description: "Sites can be organized into groups of documents called workspaces."
  - name: docs
    description: "Workspaces contain collections of Grist documents."
  - name: records
    description: "Tables contain collections of records (also called rows)."
  - name: tables
    description: "Documents are structured as a collection of tables."
  - name: columns
    description: "Tables are structured as a collection of columns."
  - name: data
    description: "Work with table data, using a (now deprecated) columnar format. We now recommend the `records` endpoints."
  - name: attachments
    description: "Documents may include attached files. Data records can refer to these using a column of type `Attachments`."
  - name: webhooks
    description: "Document changes can trigger requests to URLs called webhooks."
  - name: sql
    description: "Sql endpoint to query data from documents."
  - name: users
    description: "Grist users."
  - name: service accounts
    description: "Impersonations to manage grist resources through REST APIs with specific rights."
  - name: scim
    description: "SCIM"
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: "Authorization: Bearer XXXXXXXXXXX"
      description: "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."
  schemas:
    Org:
      type: object
      required:
        - id
        - name
        - domain
        - owner
        - createdAt
        - updatedAt
        - access
      properties:
        id:
          type: integer
          format: int64
          example: 42
        name:
          type: string
          example: "Grist Labs"
        domain:
          type: string
          nullable: true
          example: "gristlabs"
        owner:
          type: object
          $ref: "#/components/schemas/User"
          nullable: true
        access:
          type: string
          $ref: "#/components/schemas/Access"
        createdAt:
          type: string
          example: "2019-09-13T15:42:35.000Z"
        updatedAt:
          type: string
          example: "2019-09-13T15:42:35.000Z"
    Orgs:
      type: array
      items:
        $ref: "#/components/schemas/Org"
    DocComparison:
      type: object
      description: "Comparison result between two document versions"
      required:
        - left
        - right
        - parent
        - summary
      properties:
        left:
          type: object
          description: "Left/local document state"
          properties:
            n:
              type: integer
              description: "Sequential action number"
            h:
              type: string
              description: "Hash identifier"
        right:
          type: object
          description: "Right/remote document state"
          properties:
            n:
              type: integer
            h:
              type: string
        parent:
          type: object
          nullable: true
          description: "Most recent common ancestor state"
          properties:
            n:
              type: integer
            h:
              type: string
        summary:
          type: string
          enum: ["same", "left", "right", "both", "unrelated"]
          description: |
            Relationship summary:
            - same: documents have the same most recent state
            - left: the left document has actions not yet in the right
            - right: the right document has actions not yet in the left
            - both: both documents have changes (possible divergence)
            - unrelated: no common history found
        details:
          type: object
          description: "Detailed change information (when requested)"
          properties:
            leftChanges:
              type: object
              description: "Changes in the left document relative to common ancestor"
            rightChanges:
              type: object
              description: "Changes in the right document relative to common ancestor"
    Webhooks:
      type: array
      items:
        $ref: "#/components/schemas/Webhook"
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx"
        fields:
          $ref: "#/components/schemas/WebhookFields"
        usage:
          $ref: "#/components/schemas/WebhookUsage"
    WebhookFields:
      allOf:
        - $ref: "#/components/schemas/WebhookPartialFields"
        - $ref: "#/components/schemas/WebhookRequiredFields"
    WebhookRequiredFields:
      type: object
      required:
        - name
        - memo
        - url
        - enabled
        - unsubscribeKey
        - eventTypes
        - isReadyColumn
        - tableId
      properties:
        unsubscribeKey:
          type: string
    WebhookPartialFields:
      type: object
      properties:
        name:
          type: string
          example: "new-project-email"
          nullable: true
        memo:
          type: string
          example: "Send an email when a project is added"
          nullable: true
        url:
          type: string
          format: uri
          example: "https://example.com/webhook/123"
        enabled:
          type: boolean
        eventTypes:
          type: array
          items:
            type: string
          example:
            - add
            - update
        isReadyColumn:
          type: string
          nullable: true
          example: null
        tableId:
          type: string
          example: "Projects"
    WebhookUsage:
      type: object
      nullable: true
      required:
        - numWaiting
        - status
      properties:
        numWaiting:
          type: integer
        status:
          type: string
          example: "idle"
        updatedTime:
          type: number
          nullable: true
          format: "UNIX epoch in milliseconds"
          example: 1685637500424
        lastSuccessTime:
          type: number
          nullable: true
          format: "UNIX epoch in milliseconds"
          example: 1685637500424
        lastFailureTime:
          type: number
          nullable: true
          format: "UNIX epoch in milliseconds"
          example: 1685637500424
        lastErrorMessage:
          type: string
          nullable: true
          example: null
        lastHttpStatus:
          type: number
          nullable: true
          example: 200
        lastEventBatch:
          $ref: "#/components/schemas/WebhookBatchStatus"
    WebhookBatchStatus:
      type: object
      nullable: true
      required:
        - size
        - attempts
        - status
      properties:
        size:
          type: number
          example: 1
        attempts:
          type: number
          example: 1
        errorMessage:
          type: string
          nullable: true
          example: null
        httpStatus:
          type: number
          example: 200
        status:
          type: string
          example: "success"
    WebhookId:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Webhook identifier
          example: "xxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx"
    WebhookRequiredProperties:
      type: object
      required:
        - size
      properties:
        size:
          type: number
          example: 1
    WebhookProperties:
      size:
        type: number
        example: 1
      attempts:
        type: number
        example: 1
      errorMessage:
        type: string
        nullable: true
        example: null
      httpStatus:
        type: number
        example: 200
      status:
        type: string
        example: "success"
    Workspace:
      type: object
      required:
        - id
        - name
        - access
      properties:
        id:
          type: integer
          format: int64
          example: 97
        name:
          type: string
          example: Secret Plans
        access:
          type: string
          $ref: "#/components/schemas/Access"
    Doc:
      type: object
      required:
        - id
        - name
        - isPinned
        - urlId
        - access
      properties:
        id:
          type: string
          example: 145
        name:
          type: string
          example: Project Lollipop
        access:
          type: string
          $ref: "#/components/schemas/Access"
        isPinned:
          type: boolean
          example: true
        urlId:
          type: string
          nullable: true
          example: null
    WorkspaceWithDocs:
      allOf:
        - $ref: "#/components/schemas/Workspace"
        - type: object
          required:
          - docs
          properties:
            docs:
              type: array
              items:
                $ref: "#/components/schemas/Doc"
    WorkspaceWithDocsAndDomain:
      allOf:
        - $ref: "#/components/schemas/WorkspaceWithDocs"
        - type: object
          properties:
            orgDomain:
              type: string
              example: "gristlabs"
    WorkspaceWithOrg:
      allOf:
        - $ref: "#/components/schemas/Workspace"
        - type: object
          required:
          - org
          properties:
            org:
              $ref: "#/components/schemas/Org"
    WorkspaceWithDocsAndOrg:
      allOf:
        - $ref: "#/components/schemas/WorkspaceWithDocs"
        - $ref: "#/components/schemas/WorkspaceWithOrg"
    DocWithWorkspace:
      allOf:
        - $ref: "#/components/schemas/Doc"
        - type: object
          required:
          - workspace
          properties:
            workspace:
              $ref: "#/components/schemas/WorkspaceWithOrg"
    User:
      type: object
      required:
        - id
        - name
        - picture
      properties:
        id:
          type: integer
          format: int64
          example: 101
        name:
          type: string
          example: "Helga Hufflepuff"
        picture:
          type: string
          nullable: true
          example: null
    Access:
      type: string
      enum:
        - owners
        - editors
        - viewers
    Data:
      type: object
      required:
        - id
      properties:
        id:
          type: array
          items:
            type: integer
      additionalProperties:
        type: array
        items:
          type: object
      example:
        id: [1, 2]
        pet: ["cat", "dog"]
        popularity: [67, 95]
    DataWithoutId:
      type: object
      additionalProperties:
        type: array
        items:
          type: object
      example:
        pet: ["cat", "dog"]
        popularity: [67, 95]
    RecordsList:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          items:
            type: object
            required:
              - id
              - fields
            properties:
              id:
                type: number
                example: 1
              fields:
                type: object
                description: "A JSON object mapping column names to [cell values](https://support.getgrist.com/code/modules/GristData/#cellvalue)."
      example:
        records:
          -
            id: 1
            fields:
              pet: cat
              popularity: 67
          -
            id: 2
            fields:
              pet: dog
              popularity: 95
    RecordsWithoutId:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          items:
            type: object
            required:
              - fields
            properties:
              fields:
                type: object
                description: "A JSON object mapping column names to [cell values](https://support.getgrist.com/code/modules/GristData/#cellvalue)."
      example:
        records:
          -
            fields:
              pet: cat
              popularity: 67
          -
            fields:
              pet: dog
              popularity: 95
    RecordsWithoutFields:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: number
                example: 1
      example:
        records:
          -
            id: 1
          -
            id: 2
    RecordsWithRequire:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          items:
            type: object
            required:
              - require
            properties:
              require:
                type: object
                description: >
                  keys are column identifiers, and values are
                  [cell values](https://support.getgrist.com/code/modules/GristData/#cellvalue)
                  we want to have in those columns (either by matching
                  with an existing record, or creating a new record)
              fields:
                type: object
                description: >
                  keys are column identifiers, and values are
                  [cell values](https://support.getgrist.com/code/modules/GristData/#cellvalue)
                  to place in those columns (either overwriting values in an existing
                  record, or in a new record)
      example:
        records:
          - require:
              pet: cat
            fields:
              popularity: 67
          - require:
              pet: dog
            fields:
              popularity: 95

    TablesList:
      type: object
      required:
        - tables
      properties:
        tables:
          type: array
          items:
            type: object
            required:
              - id
              - fields
            properties:
              id:
                type: string
                example: Table1
              fields:
                type: object
                properties:
                  tableRef:
                    type: integer
                    description: Row ID of the table in the _grist_Tables metadata table
                  onDemand:
                    type: boolean
                    description: Whether the table uses on-demand loading
      example:
        tables:
          - id: People
            fields:
              tableRef: 1
              onDemand: false
          - id: Places
            fields:
              tableRef: 2
              onDemand: false
    TablesWithoutFields:
      type: object
      required:
        - tables
      properties:
        tables:
          type: array
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
                example: Table1
      example:
        tables:
          - id: People
          - id: Places
    CreateTables:
      type: object
      required:
        - tables
      properties:
        tables:
          type: array
          items:
            type: object
            required:
              - columns
            properties:
              id:
                type: string
                example: Table1
              columns:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      example: ColumnName
                    fields:
                      type: object
      example:
        tables:
          - id: People
            columns:
              - id: pet
                fields:
                  label: "Pet"
              - id: popularity
                fields:
                  label: "Popularity ❤"

    ColumnsList:
      type: object
      properties:
        columns:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: ColumnName
              fields:
                $ref: "#/components/schemas/GetFields"
      example:
        columns:
          - id: pet
            fields:
              label: "Pet"
          - id: popularity
            fields:
              label: "Popularity ❤"
              type: "Int"
    CreateColumns:
      type: object
      required:
        - columns
      properties:
        columns:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Column identifier
              fields:
                $ref: "#/components/schemas/CreateFields"
      example:
        columns:
          - id: pet
            fields:
              label: "Pet"
          - id: popularity
            fields:
              label: "Popularity ❤"
              type: Int
          - id: Order
            fields:
              type: Ref:Orders
              visibleCol: 2
          - id: Formula
            fields:
              type: Int
              formula: $A + $B
              isFormula: true
          - id: Status
            fields:
              type: Choice
              widgetOptions: "{\"choices\":[\"New\",\"Old\"],\"choiceOptions\":{\"New\":{\"fillColor\":\"#FF0000\",\"textColor\":\"#FFFFFF\"}}}"
    UpdateTables:
      type: object
      required:
        - tables
      properties:
        tables:
          type: array
          items:
            type: object
            required:
              - id
              - fields
            properties:
              id:
                type: string
                description: Current table identifier
              fields:
                type: object
                properties:
                  tableId:
                    type: string
                    description: Set to a new value to rename the table
                  onDemand:
                    type: boolean
                    description: Whether the table should use on-demand loading
      example:
        tables:
          - id: People
            fields:
              tableId: Persons
          - id: Places
            fields:
              onDemand: true
    UpdateColumns:
      type: object
      required:
        - columns
      properties:
        columns:
          type: array
          items:
            type: object
            required:
              - id
              - fields
            properties:
              id:
                type: string
                description: Column identifier
              fields:
                allOf:
                  - $ref: "#/components/schemas/CreateFields"
                  - type: object
                    properties:
                      colId:
                        type: string
                        description: Set it to the new column ID when you want to change it.
      example:
        columns:
          - id: pet
            fields:
              label: "Pet"
          - id: popularity
            fields:
              label: "Popularity ❤"
              type: Int
    ColumnsWithoutFields:
      type: object
      required:
        - columns
      properties:
        columns:
          type: array
          items:
            type: object
            required:
              - id
            properties:
              id:
                type: string
                example: ColumnName
      example:
        columns:
          - id: pet
          - id: popularity
    Fields:
      type: object
      properties:
        type:
          type: string
          description: "Column type, by default Any. Ref, RefList and DateTime types requires a postfix, e.g. <code>DateTime:America/New_York</code>, <code>Ref:Users</code>"
          enum: [Any, Text, Numeric, Int, Bool, Date, DateTime:<timezone>, Choice, ChoiceList, Ref:<tableId>, RefList:<tableId>, Attachments]
        label:
          type: string
          description: Column label.
        formula:
          type: string
          description: "A python formula, e.g.: <code>$A + Table1.lookupOne(B=$B)</code>"
        isFormula:
          type: boolean
          description: Use "true" to indicate that the column is a formula column. Use "false" for trigger formula column.
        widgetOptions:
          type: string
          description: "A JSON object with widget options, e.g.: <code>{\"choices\": [\"cat\", \"dog\"], \"alignment\": \"right\"}</code>"
        untieColIdFromLabel:
          type: boolean
          description: "Use \"true\" to indicate that the column label should not be used as the column identifier. Use \"false\" to use the label as the identifier."
        recalcWhen:
          type: integer
          description: "A number indicating when the column should be recalculated. <ol start='0'><li>On new records or when any field in recalcDeps changes, it's a 'data-cleaning'.</li><li>Never.</li><li>Calculate on new records and on manual updates to any data field.</li></ol>"
        visibleCol:
          type: integer
          description: "For Ref and RefList columns, the colRef of a column to display"
    CreateFields:
      allOf:
        - $ref: '#/components/schemas/Fields'
        - type: object
          properties:
            recalcDeps:
              type: string
              description: "An encoded array of column identifiers (colRefs) that this column depends on. If any of these columns change, the column will be recalculated. E.g.: <code>[2, 3]</code>"
    GetFields:
      allOf:
        - $ref: '#/components/schemas/Fields'
        - type: object
          properties:
            recalcDeps:
              type: array
              items:
                type: integer
              description: "An array of column identifiers (colRefs) that this column depends on, prefixed with \"L\" constant. If any of these columns change, the column will be recalculated. E.g.: <code>[\"L\", 2, 3]</code>"
            colRef:
              type: integer
              description: "Column reference, e.g.: <code>2</code>"
    RowIds:
      type: array
      example: [101, 102, 103]
      items:
        type: integer
    DocParameters:
      type: object
      properties:
        name:
          type: string
          example: "Competitive Analysis"
        isPinned:
          type: boolean
          example: false
    WorkspaceParameters:
      type: object
      properties:
        name:
          type: string
          example: "Retreat Docs"
    OrgParameters:
      type: object
      properties:
        name:
          type: string
          example: "ACME Unlimited"
    OrgAccessRead:
      type: object
      required:
        - users
      properties:
        users:
          type: array
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: "Andrea"
              email:
                type: string
                example: "andrea@getgrist.com"
              access:
                $ref: "#/components/schemas/Access"
    OrgAccessWrite:
      type: object
      required:
        - users
      properties:
        users:
          type: object
          additionalProperties:
            type: string
            enum:
              - owners
              - editors
              - viewers
              - members
              - null
          example:
            "foo@getgrist.com": "owners"
            "bar@getgrist.com": null
    WorkspaceAccessRead:
      type: object
      required:
        - maxInheritedRole
        - users
      properties:
        maxInheritedRole:
          $ref: "#/components/schemas/Access"
        users:
          type: array
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: "Andrea"
              email:
                type: string
                example: "andrea@getgrist.com"
              access:
                $ref: "#/components/schemas/Access"
              parentAccess:
                $ref: "#/components/schemas/Access"
    WorkspaceAccessWrite:
      type: object
      properties:
        maxInheritedRole:
          $ref: "#/components/schemas/Access"
        users:
          type: object
          additionalProperties:
            type: string
            enum:
              - owners
              - editors
              - viewers
              - members
              - null
          example:
            "foo@getgrist.com": "owners"
            "bar@getgrist.com": null
    DocAccessWrite:
      $ref: "#/components/schemas/WorkspaceAccessWrite"
    DocAccessRead:
      $ref: "#/components/schemas/WorkspaceAccessRead"
    AttachmentUpload:
      type: object
      properties:
        upload:
          type: array
          items:
            type: string
            format: binary
    AttachmentId:
      type: number
      description: An integer ID
    AttachmentMetadata:
      type: object
      properties:
        fileName:
          type: string
          example: "logo.png"
        fileSize:
          type: number
          example: 12345
        timeUploaded:
          type: string
          example: "2020-02-13T12:17:19.000Z"
    AttachmentMetadataList:
      type: object
      required:
        - records
      properties:
        records:
          type: array
          items:
            type: object
            required:
              - id
              - fields
            properties:
              id:
                type: number
                example: 1
              fields:
                $ref: "#/components/schemas/AttachmentMetadata"
    SqlResultSet:
      type: object
      required:
        - statement
        - records
      properties:
        statement:
          type: string
          description: "A copy of the SQL statement."
          example: "select * from Pets ..."
        records:
          type: array
          items:
            type: object
            required:
              - fields
            properties:
              fields:
                type: object
          example:
          -
            fields:
              id: 1
              pet: cat
              popularity: 67
          -
            fields:
              id: 2
              pet: dog
              popularity: 95
    TableSchemaResult:
      type: object
      required:
        - name
        - title
        - schema
      properties:
        name:
          type: string
          description: "The ID (technical name) of the table"
        title:
          type: string
          description: "The human readable name of the table"
        path:
          type: string
          description: "The URL to download the CSV"
          example: "https://getgrist.com/o/docs/api/docs/ID/download/csv?tableId=Table1&...."
        format:
          type: string
          enum: ["csv"]
        mediatype:
          type: string
          enum: ["text/csv"]
        encoding:
          type: string
          enum: ["utf-8"]
        dialect:
          $ref: "https://specs.frictionlessdata.io/schemas/csv-dialect.json"
        schema:
          $ref: "https://specs.frictionlessdata.io/schemas/table-schema.json"
    CreateServiceAccount:
      allOf:
        - $ref: '#/components/schemas/ServiceAccountBody'
        - type: object
          required:
            - expiresAt
    ServiceAccountBody:
      type: object
      properties:
        label:
          type: string
          description: "The service account's display name"
          example: "n8n"
        description:
          type: string
          description: "Description of service account's purpose"
          example: "For data update workflow"
        expiresAt:
          type: string
          description: "The service account's expiration date"
          example: "2042-10-10"
    ServiceAccountResultWithApiKey:
      allOf:
        - $ref: "#/components/schemas/ServiceAccountResult"
        - type: object
          required:
            - apikey
          properties:
            key:
              type: string
              example: "1234567890abcdef"
    ServiceAccountResult:
      type: object
      required:
        - id
        - login
        - label
        - description
        - expiresAt
        - hasValidKey
      properties:
        id:
          type: number
          example: 42
        login:
          type: string
          example: "aa52e4c7-e451-409a-8140-4eb17844e8b9@serviceaccounts.invalid"
        label:
          type: string
          example: "n8n"
        description:
          type: string
          example: "For data import workflow"
        expiresAt:
          type: date
          example: "2042-10-10T00:00:00.000Z"
        hasValidKey:
          type: boolean
          example: true
    ServiceAccountsResult:
      type: array
      items:
        $ref: "#/components/schemas/ServiceAccountResult"
    DocumentStoreSetting:
      type: object
      properties:
        type:
          type: string
          enum: [ 'external', 'internal' ]
    DocumentStoreId:
      type: string
      nullable: true
      example: "83395209-fc3b-4d02-8934-b2619efec712-filesystem"
    DocumentAttachmentsLocation:
      type: string
      description: "The current location of attachment files in the document"
      enum:
        - none
        - internal
        - mixed
        - external
      example: mixed
    AttachmentsTransferStatus:
      type: object
      properties:
        status:
          type: object
          properties:
            pendingTransferCount:
              type: integer
              description: "Remaining transfers be performed"
              example: 19
            isRunning:
              type: boolean
              description: "Are files actively being transferred?"
              example: true
        locationSummary:
          $ref: '#/components/schemas/DocumentAttachmentsLocation'



  parameters:
    filterQueryParam:
      in: query
      name: filter
      schema:
        type: string
      description: "This is a JSON object mapping column names to arrays of allowed values.  For example, to filter column `pet` for values `cat` and `dog`, the filter would be `{\"pet\": [\"cat\", \"dog\"]}`. JSON contains characters that are not safe to place in a URL, so it is important to url-encode them.  For this example, the url-encoding is `%7B%22pet%22%3A%20%5B%22cat%22%2C%20%22dog%22%5D%7D`. See https://rosettacode.org/wiki/URL_encoding for how to url-encode a string, or https://www.urlencoder.org/ to try some examples. Multiple columns can be filtered. For example the filter for `pet` being either `cat` or `dog`, AND `size` being either `tiny` or `outrageously small`, would be `{\"pet\": [\"cat\", \"dog\"], \"size\": [\"tiny\", \"outrageously small\"]}`."
      example: "{\"pet\": [\"cat\", \"dog\"]}"
      required: false
    sortQueryParam:
      in: query
      name: sort
      schema:
        type: string
      description: "Order in which to return results. If a single column name is given (e.g. `pet`), results are placed in ascending order of values in that column. To get results in an order that was previously prepared manually in Grist, use the special `manualSort` column name. Multiple columns can be specified, separated by commas (e.g. `pet,age`). For descending order, prefix a column name with a `-` character (e.g. `pet,-age`). To include additional sorting options append them after a colon (e.g. `pet,-age:naturalSort;emptyFirst,owner`). Available options are: `choiceOrder`, `naturalSort`, `emptyFirst`. Without the `sort` parameter, the order of results is unspecified."
      example: "pet,-age"
      required: false
    limitQueryParam:
      in: query
      name: limit
      schema:
        type: number
      description: "Return at most this number of rows.  A value of 0 is equivalent to having no limit."
      example: "5"
      required: false
    sortHeaderParam:
      in: header
      name: X-Sort
      schema:
        type: string
      description: "Same as `sort` query parameter."
      example: "pet,-age"
      required: false
    limitHeaderParam:
      in: header
      name: X-Limit
      schema:
        type: number
      description: "Same as `limit` query parameter."
      example: "5"
      required: false
    colIdPathParam:
      in: path
      name: colId
      schema:
        type: string
      description: The column id (without the starting `$`) as shown in the column configuration below the label
      required: true
    tableIdPathParam:
      in: path
      name: tableId
      schema:
        type: string
      description: normalized table name (see `TABLE ID` in Raw Data) or numeric row ID in `_grist_Tables`
      required: true
    docIdPathParam:
      in: path
      name: docId
      schema:
        type: string
      description: A string id (UUID)
      required: true
    orgIdPathParam:
      in: path
      name: orgId
      schema:
        oneOf:
          - type: integer
          - type: string
      description: 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
      required: true
    workspaceIdPathParam:
      in: path
      name: workspaceId
      description: An integer id
      schema:
        type: integer
      required: true
    userIdPathParam:
      in: path
      name: userId
      schema:
        type: integer
      description: A user id
      required: true
    noparseQueryParam:
      in: query
      name: noparse
      schema:
        type: boolean
      description: "Set to true to prohibit parsing strings according to the column type."
    hiddenQueryParam:
      in: query
      name: hidden
      schema:
        type: boolean
      description: "Set to true to include the hidden columns (like \"manualSort\")"
    headerQueryParam:
      in: query
      name: header
      schema:
        type: string
        enum:
          - colId
          - label
      description: "Format for headers. Labels tend to be more human-friendly while colIds are more normalized."
      required: false
    saIdPathParam:
      in: path
      name: saId
      schema:
        type: integer
      description: A service account id