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


    # Authentication

    <SecurityDefinitions />

    '
  version: 1.0.1
  title: Grist attachments tables API
servers:
- url: https://{gristhost}/api
  variables:
    subdomain:
      description: The team name, or `docs` for personal areas
      default: docs
security:
- ApiKey: []
tags:
- name: tables
  description: Documents are structured as a collection of tables.
paths:
  /docs/{docId}/tables:
    get:
      operationId: listTables
      tags:
      - tables
      summary: List tables in a document
      parameters:
      - $ref: '#/components/parameters/docIdPathParam'
      - $ref: '#/components/parameters/expandQueryParam'
      responses:
        200:
          description: The tables in a document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TablesList'
              examples:
                default:
                  summary: Without expand
                  value:
                    tables:
                    - id: People
                      fields:
                        tableRef: 1
                        onDemand: false
                    - id: Places
                      fields:
                        tableRef: 2
                        onDemand: false
                expanded:
                  summary: With ?expand=column
                  value:
                    tables:
                    - id: People
                      fields:
                        tableRef: 1
                        onDemand: false
                      columns:
                      - id: Name
                        fields:
                          colRef: 2
                          label: Name
                          isFormula: false
                          type: Text
                          parentId: 1
                          formula: ''
                      - id: Age
                        fields:
                          colRef: 3
                          label: Age
                          isFormula: false
                          type: Numeric
                          parentId: 1
                          formula: ''
    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
components:
  parameters:
    docIdPathParam:
      in: path
      name: docId
      schema:
        type: string
      description: A string id (UUID)
      required: true
    expandQueryParam:
      in: query
      name: expand
      schema:
        type: string
        enum:
        - column
      description: Set to "column" to include column metadata for each table in the response.
      required: false
  schemas:
    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>'
    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 ❤
    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
    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
    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
    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
              columns:
                type: array
                description: Included when expand=column is set. Contains metadata for each column in the table.
                items:
                  type: object
                  required:
                  - id
                  - fields
                  properties:
                    id:
                      type: string
                      example: ColumnName
                    fields:
                      $ref: '#/components/schemas/GetFields'
      example:
        tables:
        - id: People
          fields:
            tableRef: 1
            onDemand: false
        - id: Places
          fields:
            tableRef: 2
            onDemand: false
  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.