openapi: 3.0.0
info:
  description: 'An API for manipulating Grist sites, workspaces, and documents.


    # Authentication

    <SecurityDefinitions />

    '
  version: 1.0.1
  title: Grist attachments docs API
servers:
- url: https://{gristhost}/api
  variables:
    subdomain:
      description: The team name, or `docs` for personal areas
      default: docs
security:
- ApiKey: []
tags:
- name: docs
  description: Workspaces contain collections of Grist documents.
paths:
  /workspaces/{workspaceId}/docs:
    post:
      operationId: createDoc
      tags:
      - docs
      summary: Create an empty document
      parameters:
      - $ref: '#/components/parameters/workspaceIdPathParam'
      requestBody:
        description: settings for the document
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocParameters'
        required: true
      responses:
        200:
          description: The document id
          content:
            application/json:
              schema:
                type: string
                description: a unique identifier for the document
                example: 9PJhBDZPyCNoayZxaCwFfS
  /workspaces/{workspaceId}/import:
    post:
      operationId: importDoc
      tags:
      - docs
      summary: Import an existing document
      parameters:
      - $ref: '#/components/parameters/workspaceIdPathParam'
      requestBody:
        description: settings for the document
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upload:
                  description: Contents of a .grist file, as a standard multipart/form-data file entry
                  type: string
                  format: binary
                documentName:
                  type: string
                  example: Example Doc
        required: true
      responses:
        200:
          description: The document id
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: a unique identifier for the document
                    example: 9PJhBDZPyCNoayZxaCwFfS
  /docs:
    post:
      operationId: createDocUnified
      tags:
      - docs
      summary: Create a document
      description: 'A unified endpoint for creating documents. Can create an empty document,

        copy an existing document, or import a file.


        - To create an empty unsaved document: provide no parameters

        - To create an empty saved document: provide `workspaceId`

        - To copy an existing document: provide `sourceDocumentId`, `workspaceId`, and `documentName`

        - To import a file: use multipart/form-data with a file upload and optional `workspaceId`

        '
      requestBody:
        description: settings for the document
        content:
          application/json:
            schema:
              type: object
              properties:
                workspaceId:
                  type: integer
                  description: The workspace to save the document in. If omitted, creates an unsaved document.
                  example: 97
                documentName:
                  type: string
                  description: Name for the new document (required when copying)
                  example: My Document
                sourceDocumentId:
                  type: string
                  description: ID of document to copy from. Requires workspaceId and documentName.
                  example: mNnQ2PXndhXm
                asTemplate:
                  type: boolean
                  description: When copying, if true, copy structure only without data
                  example: false
                timezone:
                  type: string
                  description: Timezone for the document
                  example: America/New_York
          multipart/form-data:
            schema:
              type: object
              properties:
                upload:
                  description: File to import (.grist, .xlsx, .csv, etc.)
                  type: string
                  format: binary
                workspaceId:
                  type: integer
                  description: The workspace to save the document in
                documentName:
                  type: string
                  description: Name for the imported document
      responses:
        200:
          description: The document id
          content:
            application/json:
              schema:
                type: string
                description: a unique identifier for the document
                example: 9PJhBDZPyCNoayZxaCwFfS
  /docs/{docId}:
    get:
      operationId: describeDoc
      tags:
      - docs
      summary: Describe a document
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: A document's metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocWithWorkspace'
    patch:
      operationId: modifyDoc
      tags:
      - docs
      summary: Modify document metadata (but not its contents)
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: the changes to make
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocParameters'
        required: true
      responses:
        200:
          description: Success
    delete:
      operationId: deleteDoc
      tags:
      - docs
      summary: Delete a document
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Success
  /docs/{docId}/remove:
    post:
      operationId: removeDoc
      tags:
      - docs
      summary: Move document to trash
      description: 'Soft-delete the document by moving it to trash. The document can be

        restored using the unremove endpoint. If the `permanent` query parameter

        is set to true, the document is permanently deleted instead.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: permanent
        schema:
          type: boolean
        description: If true, permanently delete instead of moving to trash
      responses:
        200:
          description: Document moved to trash (or permanently deleted)
  /docs/{docId}/unremove:
    post:
      operationId: unremoveDoc
      tags:
      - docs
      summary: Restore document from trash
      description: 'Recover a document that was previously soft-deleted. Only works if the

        document is still in the trash.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document restored successfully
  /docs/{docId}/move:
    patch:
      operationId: moveDoc
      tags:
      - docs
      summary: Move document to another workspace.
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: the target workspace
        content:
          application/json:
            schema:
              type: object
              required:
              - workspace
              properties:
                workspace:
                  type: integer
                  example: 597
      responses:
        200:
          description: Document moved successfully. Returns empty body.
  /docs/{docId}/pin:
    patch:
      operationId: pinDoc
      tags:
      - docs
      summary: Pin a document
      description: 'Pin the document so it appears in a prominent location. Pinned documents

        are displayed at the top of workspace listings for easy access.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document pinned successfully
  /docs/{docId}/unpin:
    patch:
      operationId: unpinDoc
      tags:
      - docs
      summary: Unpin a document
      description: Remove the pinned status from a document.
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document unpinned successfully
  /docs/{docId}/disable:
    post:
      operationId: disableDoc
      tags:
      - docs
      summary: Disable a document.
      description: 'Disabled documents cannot be accessed or modified. Moving and

        renaming a disabled doc is also forbidden, as well as

        accessing or submitting published forms associated to a

        disabled document.


        Disabled documents, however, can be moved to and restored from

        the trash.


        The operation is non-destructive. Disabled documents can be

        re-enabled.


        Only admin accounts can disable a document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document disabled successfully. Returns empty body.
        403:
          description: The caller is not allowed to disable this document
        404:
          description: The document is not found
  /docs/{docId}/enable:
    post:
      operationId: enableDoc
      tags:
      - docs
      summary: Enable a document.
      description: 'If a document has been previously disabled, this will restore

        all former access to a document, including access to its

        associated published forms.


        Only admin accounts can enable a document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document enabled successfully. Returns empty body.
        403:
          description: The caller is not allowed to enable this document
        404:
          description: The document is not found
  /docs/{docId}/copy:
    post:
      operationId: copyDoc
      tags:
      - docs
      summary: Copies a document to a workspace.
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: the target workspace
        content:
          application/json:
            schema:
              type: object
              required:
              - workspaceId
              - documentName
              properties:
                workspaceId:
                  type: integer
                  example: 597
                documentName:
                  type: string
                  example: Example Doc
                asTemplate:
                  type: boolean
                  description: Remove all data and history but keep the structure to use the document as a template
      responses:
        200:
          description: The document id
          content:
            application/json:
              schema:
                description: a unique identifier for the document
                type: string
                example: '145'
  /docs/{docId}/fork:
    post:
      operationId: forkDoc
      tags:
      - docs
      summary: Fork a document
      description: 'Create a fork of a document. A fork is a personal copy that tracks its relationship

        to the original document. Forks can be used to experiment with changes before

        applying them to the original.


        The fork will have a new docId and urlId that encode the relationship to the trunk

        (original) document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Fork created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - forkId
                - docId
                - urlId
                properties:
                  forkId:
                    type: string
                    description: The unique identifier for this fork
                    example: abc123
                  docId:
                    type: string
                    description: The full document ID of the fork
                    example: XXXXX~abc123
                  urlId:
                    type: string
                    description: The URL-friendly ID of the fork
                    example: UUUUU~abc123
        400:
          description: Cannot fork a document that's already a fork
        403:
          description: Insufficient access to document to copy it entirely
  /docs/{docId}/access:
    get:
      operationId: listDocAccess
      tags:
      - docs
      summary: List users with access to document
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Users with access to document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocAccessRead'
    patch:
      operationId: modifyDocAccess
      tags:
      - docs
      summary: Change who has access to document
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        description: the changes to make
        content:
          application/json:
            schema:
              type: object
              required:
              - delta
              properties:
                delta:
                  $ref: '#/components/schemas/DocAccessWrite'
        required: true
      responses:
        200:
          description: Success
  /docs/{docId}/usersForViewAs:
    get:
      operationId: getUsersForViewAs
      tags:
      - docs
      summary: Get users for 'View As' feature
      description: 'Get users that can be used with the "View As" feature for testing access rules.

        Only document owners can call this endpoint.


        Users are drawn from:

        - Users the document is shared with

        - Users mentioned in user attribute tables

        - Predefined example users

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Users available for View As
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    description: Users the document is shared with
                    items:
                      $ref: '#/components/schemas/User'
                  attributeTableUsers:
                    type: array
                    description: Users found in user attribute tables
                    items:
                      $ref: '#/components/schemas/User'
                  exampleUsers:
                    type: array
                    description: Predefined example users
                    items:
                      $ref: '#/components/schemas/User'
  /docs/{docId}/download:
    get:
      operationId: downloadDoc
      tags:
      - docs
      summary: Content of document, as an Sqlite file
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: nohistory
        schema:
          type: boolean
          description: Remove document history (can significantly reduce file size)
        required: false
      - in: query
        name: template
        schema:
          type: boolean
          description: Remove all data and history but keep the structure to use the document as a template
        required: false
      responses:
        200:
          description: A document's content in Sqlite form
          content:
            application/x-sqlite3:
              schema:
                type: string
                format: binary
  /docs/{docId}/download/xlsx:
    get:
      operationId: downloadDocXlsx
      tags:
      - docs
      summary: Content of document, as an Excel file
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - $ref: '#/components/parameters/headerQueryParam'
      - in: query
        name: tableId
        schema:
          type: string
          description: Name of a table (normalized).
      responses:
        200:
          description: A document's content in Excel form
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
  /docs/{docId}/download/csv:
    get:
      operationId: downloadDocCsv
      tags:
      - docs
      summary: Content of table, as a CSV file
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: tableId
        schema:
          type: string
          description: Name of a table (normalized).
        required: true
      - $ref: '#/components/parameters/headerQueryParam'
      responses:
        200:
          description: A table's content in CSV form
          content:
            text/csv:
              schema:
                type: string
  /docs/{docId}/download/tsv:
    get:
      operationId: downloadDocTsv
      tags:
      - docs
      summary: Content of table, as a TSV file
      description: Download table data as tab-separated values.
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: tableId
        schema:
          type: string
          description: Name of a table (normalized).
        required: true
      - $ref: '#/components/parameters/headerQueryParam'
      responses:
        200:
          description: A table's content in TSV form
          content:
            text/tab-separated-values:
              schema:
                type: string
  /docs/{docId}/download/dsv:
    get:
      operationId: downloadDocDsv
      tags:
      - docs
      summary: Content of table, as a DSV file
      description: Download table data using a custom delimiter (💩).
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: tableId
        schema:
          type: string
          description: Name of a table (normalized).
        required: true
      - $ref: '#/components/parameters/headerQueryParam'
      responses:
        200:
          description: A table's content in DSV form
          content:
            text/plain:
              schema:
                type: string
  /docs/{docId}/download/table-schema:
    get:
      operationId: downloadTableSchema
      tags:
      - docs
      summary: The schema of a table
      description: The schema follows [frictionlessdata's table-schema standard](https://specs.frictionlessdata.io/table-schema/).
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: tableId
        schema:
          type: string
          description: Name of a table (normalized).
        required: true
      - $ref: '#/components/parameters/headerQueryParam'
      responses:
        200:
          description: A table's table-schema in JSON format.
          content:
            text/json:
              schema:
                $ref: '#/components/schemas/TableSchemaResult'
  /docs/{docId}/snapshots:
    get:
      operationId: listSnapshots
      tags:
      - docs
      summary: List document snapshots
      description: 'Returns a list of snapshots (backups) of the document. Snapshots are created

        automatically as the document is edited. Most recent snapshots are listed first.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: raw
        schema:
          type: boolean
        description: If true, returns all snapshots including those not in the snapshot inventory
      responses:
        200:
          description: List of snapshots
          content:
            application/json:
              schema:
                type: object
                required:
                - snapshots
                properties:
                  snapshots:
                    type: array
                    items:
                      type: object
                      required:
                      - snapshotId
                      - lastModified
                      - docId
                      properties:
                        snapshotId:
                          type: string
                          description: Unique identifier for the snapshot
                        lastModified:
                          type: string
                          format: date-time
                          description: When the snapshot was created
                        docId:
                          type: string
                          description: Document ID that can be used to open this snapshot
  /docs/{docId}/snapshots/remove:
    post:
      operationId: removeSnapshots
      tags:
      - docs
      summary: Remove document snapshots
      description: 'Remove specific snapshots from a document''s backup history.

        Only document owners can remove snapshots.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                snapshotIds:
                  type: array
                  items:
                    type: string
                  description: List of snapshot IDs to remove
              example:
                snapshotIds:
                - abc123
                - def456
      responses:
        200:
          description: Snapshots removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  snapshotIds:
                    type: array
                    items:
                      type: string
                    description: The snapshot IDs that were removed
  /docs/{docId}/states:
    get:
      operationId: getStates
      tags:
      - docs
      summary: Get document action history states
      description: 'Returns a list of document states representing the action history.

        Each state has a sequential number (n) and a hash (h) that uniquely

        identifies that point in history. Most recent state is first.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: List of document states
          content:
            application/json:
              schema:
                type: object
                required:
                - states
                properties:
                  states:
                    type: array
                    items:
                      type: object
                      required:
                      - n
                      - h
                      properties:
                        n:
                          type: integer
                          description: Sequential action number
                        h:
                          type: string
                          description: Hash identifier for this state
  /docs/{docId}/compare:
    get:
      operationId: compareVersions
      tags:
      - docs
      summary: Compare document versions
      description: 'Compare two versions of the same document by their state hashes.

        Returns details about what changed between the versions.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: left
        schema:
          type: string
        description: Hash of the left version to compare (defaults to HEAD)
      - in: query
        name: right
        schema:
          type: string
        description: Hash of the right version to compare (defaults to HEAD)
      - in: query
        name: maxRows
        schema:
          type: integer
        description: Maximum number of row changes to include in details
      responses:
        200:
          description: Comparison result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocComparison'
        403:
          description: Insufficient access to compare documents
  /docs/{docId}/compare/{docId2}:
    get:
      operationId: compareDocuments
      tags:
      - docs
      summary: Compare two documents
      description: 'Compare this document with another document. Useful for comparing

        a fork with its trunk document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - name: docId2
        in: path
        required: true
        schema:
          type: string
        description: ID of the document to compare with
      - in: query
        name: detail
        schema:
          type: boolean
        description: If true, include detailed change information
      - in: query
        name: maxRows
        schema:
          type: integer
        description: Maximum number of row changes to include
      responses:
        200:
          description: Comparison result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocComparison'
        403:
          description: Insufficient access to compare documents
  /docs/{docId}/states/remove:
    post:
      operationId: deleteActions
      tags:
      - docs
      summary: Truncate the document's action history
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - keep
              properties:
                keep:
                  type: integer
                  description: The number of the latest history actions to keep
              example:
                keep: 3
  /docs/{docId}/proposals:
    get:
      operationId: listProposals
      tags:
      - docs
      summary: List change proposals
      description: 'List proposals associated with a document. Proposals are suggested changes

        from forks that can be reviewed and applied to the trunk document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: outgoing
        schema:
          type: boolean
        description: If true, list proposals where this document is the source. Otherwise list proposals where this document is the destination.
      responses:
        200:
          description: List of proposals
          content:
            application/json:
              schema:
                type: object
                properties:
                  proposals:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Proposal ID
                        srcDocId:
                          type: string
                          description: Source document (fork) ID
                        destDocId:
                          type: string
                          description: Destination document (trunk) ID
                        retracted:
                          type: boolean
                          description: Whether the proposal has been retracted
                        comparison:
                          $ref: '#/components/schemas/DocComparison'
  /docs/{docId}/propose:
    post:
      operationId: createProposal
      tags:
      - docs
      summary: Create a change proposal
      description: 'Create a proposal from a fork to its trunk document. The proposal contains

        the comparison of changes between the fork and trunk.

        This endpoint can only be called on a fork document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                retracted:
                  type: boolean
                  description: Set to true to retract an existing proposal
                  default: false
      responses:
        200:
          description: Proposal created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    description: Proposal ID
                  comparison:
                    $ref: '#/components/schemas/DocComparison'
        400:
          description: Can only propose from a fork
  /docs/{docId}/proposals/{proposalId}/apply:
    post:
      operationId: applyProposal
      tags:
      - docs
      summary: Apply a change proposal
      description: 'Apply a proposal''s changes to the document. This merges the fork''s

        changes into the trunk document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - name: proposalId
        in: path
        required: true
        schema:
          type: integer
        description: ID of the proposal to apply
      responses:
        200:
          description: Proposal applied successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  proposalId:
                    type: integer
                  changes:
                    type: object
                    description: Summary of changes applied
  /docs/{docId}/force-reload:
    post:
      operationId: forceReload
      tags:
      - docs
      summary: Reload a document
      description: Closes and reopens the document, forcing the python engine to restart.
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Document reloaded successfully
  /docs/{docId}/flush:
    post:
      operationId: flushDoc
      tags:
      - docs
      summary: Flush document to storage
      description: 'Ensure all pending changes to the document are written to persistent storage.

        Returns true if the document was flushed, false if the document was not open.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      responses:
        200:
          description: Flush result
          content:
            application/json:
              schema:
                type: boolean
                description: True if document was flushed, false if document was not open
  /docs/{docId}/assign:
    post:
      operationId: assignDoc
      tags:
      - docs
      summary: Reassign document to appropriate worker
      description: 'Administrative endpoint that checks if a document is assigned to the expected

        worker group and frees it for reassignment if not. Used for load balancing

        and maintenance operations.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - in: query
        name: group
        schema:
          type: string
        description: Update the document's worker group (requires special permit)
      responses:
        200:
          description: Assignment result
          content:
            application/json:
              schema:
                type: boolean
                description: True if document was freed for reassignment
  /docs/{docId}/replace:
    post:
      operationId: replaceDoc
      tags:
      - docs
      summary: Replace document content
      description: 'Replace the current document content with content from another source.

        Can restore from a snapshot or copy from another document.

        '
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceDocId:
                  type: string
                  description: ID of document to copy content from
                snapshotId:
                  type: string
                  description: ID of snapshot to restore from
                resetTutorialMetadata:
                  type: boolean
                  description: Reset tutorial progress when replacing (for tutorial forks)
      responses:
        200:
          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)
components:
  schemas:
    WorkspaceWithOrg:
      allOf:
      - $ref: '#/components/schemas/Workspace'
      - type: object
        required:
        - org
        properties:
          org:
            $ref: '#/components/schemas/Org'
    Access:
      type: string
      enum:
      - owners
      - editors
      - viewers
    DocAccessWrite:
      $ref: '#/components/schemas/WorkspaceAccessWrite'
    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'
    DocAccessRead:
      $ref: '#/components/schemas/WorkspaceAccessRead'
    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
    DocParameters:
      type: object
      properties:
        name:
          type: string
          example: Competitive Analysis
        isPinned:
          type: boolean
          example: false
    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
    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
    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
    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'
    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'
    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
  parameters:
    workspaceIdPathParam:
      in: path
      name: workspaceId
      description: An integer id
      schema:
        type: integer
      required: true
    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
    docIdPathParam:
      in: path
      name: docId
      schema:
        type: string
      description: A string id (UUID)
      required: true
  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.