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


    # Authentication

    <SecurityDefinitions />

    '
  version: 1.0.1
  title: Grist attachments columns API
servers:
- url: https://{gristhost}/api
  variables:
    subdomain:
      description: The team name, or `docs` for personal areas
      default: docs
security:
- ApiKey: []
tags:
- name: columns
  description: Tables are structured as a collection of columns.
paths:
  /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
components:
  schemas:
    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>'
    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"}}}'
    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
    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
    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
  parameters:
    docIdPathParam:
      in: path
      name: docId
      schema:
        type: string
      description: A string id (UUID)
      required: true
    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
    hiddenQueryParam:
      in: query
      name: hidden
      schema:
        type: boolean
      description: Set to true to include the hidden columns (like "manualSort")
  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.