Coda Project Tables API

openapi: 3.2.0
info:
  version: 1.5.0
  title: Superhuman Docs Tables API
  license:
    name: Superhuman Developer Terms
    url: https://docs.superhuman.com/trust/developer
  description: '# Introduction


    The Superhuman Docs API is a RESTful API that lets you programmatically interact with data in Superhuman Docs (formerly Coda):


    * List and search documents

    * Create new docs and copy existing ones

    * Share and publish docs

    * Discover pages, tables, formulas, and controls

    * Read, insert, upsert, update, and delete rows


    If you plan to integrate Superhuman Docs with an AI tool, you may also want to consider using the

    Superhuman Docs MCP server.'
  termsOfService: https://superhuman.com/legal/terms
  contact:
    name: Developer Support
    url: https://superhuman.com/developers
    email: care@superhuman.com
  x-logo:
    url: https://cdn.coda.io/icons/png/color/superhuman-docs-128.png
    backgroundColor: transparent
    altText: Superhuman Docs API
    href: '#'
servers:
- url: https://docs.superhuman.com/apis/v1
  description: Superhuman Docs API (v1)
security:
- Bearer: []
tags:
- name: Tables
paths:
  /docs/{docId}/tables:
    get:
      summary: List tables
      description: Returns a list of tables in a document.
      operationId: listTables
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/docId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/sortBy'
      - $ref: '#/components/parameters/tableTypes'
      responses:
        '200':
          description: List of tables or views in a doc.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: 'import requests


          headers = {''Authorization'': ''Bearer <your API token>''}

          uri = f''https://docs.superhuman.com/apis/v1/docs/<doc ID>/tables''

          res = requests.get(uri, headers=headers).json()


          print(f''The name of the first table is {res["items"][0]["name"]}'')

          # => The name of the first table is To-do List

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/v1/docs/<doc ID>/tables' |\n  jq '.items[0].name'\n# => \"To-do List\"\n"
      - label: Google Apps Script
        lang: javascript
        source: '// Import the SuperhumanDocs library via Resource->Libraries...:

          // 15IQuWOk8MqT50FDWomh57UqWGH23gjsWVWYFms3ton6L-UHmefYHS9Vl

          SuperhumanDocs.authenticate(''<your API token>'');

          var tables = SuperhumanDocs.listTables(''<doc ID>'').items;

          Logger.log(''The name of the first table is '' + tables[0].name);

          // => The name of the first table is To-do List

          '
  /docs/{docId}/tables/{tableIdOrName}:
    get:
      summary: Get a table
      description: Returns details about a specific table or view.
      operationId: getTable
      tags:
      - Tables
      parameters:
      - $ref: '#/components/parameters/docId'
      - $ref: '#/components/parameters/tableIdOrName'
      - name: useUpdatedTableLayouts
        in: query
        description: Return "detail" and "form" for the `layout` field of detail and form layouts respectively (instead of "masterDetail" for both)
        schema:
          type: boolean
      responses:
        '200':
          description: Info about a table.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: 'import requests


          headers = {''Authorization'': ''Bearer <your API token>''}

          uri = f''https://docs.superhuman.com/apis/v1/docs/<doc ID>/tables/<table ID>''

          res = requests.get(uri, headers=headers).json()


          print(f''Table {res["name"]} has {res["rowCount"]} rows'')

          # => Table To-do List has 2 rows

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/v1/docs/<doc ID>/tables/<table ID>' |\n  jq '\"Table \" + .name + \" has \" + (.rowCount | tostring) + \" rows\"'\n# => \"Table To-do List has 2 rows\"\n"
      - label: Google Apps Script
        lang: javascript
        source: '// Import the SuperhumanDocs library via Resource->Libraries...:

          // 15IQuWOk8MqT50FDWomh57UqWGH23gjsWVWYFms3ton6L-UHmefYHS9Vl

          SuperhumanDocs.authenticate(''<your API token>'');

          var table = SuperhumanDocs.getTable(''<doc ID>'', ''<table ID>'');

          Logger.log(''Table '' + table.name + '' has '' + table.rowCount + '' rows'');

          // => Table To-do List has 2 rows

          '
components:
  parameters:
    tableTypes:
      name: tableTypes
      description: Comma-separated list of table types to include in results. If omitted, includes both tables and views.
      in: query
      explode: false
      example: table,view
      schema:
        type: array
        items:
          $ref: '#/components/schemas/TableType'
    limit:
      name: limit
      description: Maximum number of results to return in this query.
      in: query
      example: 10
      schema:
        type: integer
        minimum: 1
        default: 25
    tableIdOrName:
      name: tableIdOrName
      description: ID or name of the table. Names are discouraged because they're easily prone to being changed by users. If you're using a name, be sure to URI-encode it.
      x-sdk-description: ID or name of the table. Names are discouraged because they're easily prone to being changed by users.
      in: path
      required: true
      example: grid-pqRst-U
      schema:
        type: string
    sortBy:
      name: sortBy
      description: Determines how to sort the given objects.
      in: query
      example: name
      schema:
        $ref: '#/components/schemas/SortBy'
    pageToken:
      name: pageToken
      description: An opaque token used to fetch the next page of results.
      in: query
      example: eyJsaW1pd
      schema:
        type: string
    docId:
      name: docId
      description: ID of the doc.
      in: path
      required: true
      example: AbCDeFGH
      schema:
        type: string
  schemas:
    PageReference:
      x-schema-name: PageReference
      description: Reference to a page.
      type: object
      required:
      - id
      - type
      - browserLink
      - href
      - name
      additionalProperties: false
      properties:
        id:
          type: string
          description: ID of the page.
          example: canvas-IjkLmnO
        type:
          type: string
          description: The type of this resource.
          enum:
          - page
          x-tsType: Type.Page
        href:
          type: string
          format: url
          description: API link to the page.
          example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/pages/canvas-IjkLmnO
        browserLink:
          type: string
          format: url
          description: Browser-friendly link to the page.
          example: https://docs.superhuman.com/d/_dAbCDeFGH/Launch-Status_sumnO
        name:
          type: string
          description: Name of the page.
          example: Launch Status
    TableList:
      x-schema-name: TableList
      description: List of tables.
      type: object
      required:
      - items
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TableReference'
        href:
          type: string
          format: url
          description: API link to these results
          example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/tables?limit=20
        nextPageToken:
          $ref: '#/components/schemas/nextPageToken'
        nextPageLink:
          allOf:
          - $ref: '#/components/schemas/nextPageLink'
          - type: string
            example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/tables?pageToken=eyJsaW1pd
    Sort:
      x-schema-name: Sort
      description: A sort applied to a table or view.
      type: object
      required:
      - column
      - direction
      additionalProperties: false
      properties:
        column:
          $ref: '#/components/schemas/ColumnReference'
        direction:
          $ref: '#/components/schemas/SortDirection'
    nextPageLink:
      description: If specified, a link that can be used to fetch the next page of results.
      type: string
      format: url
    nextPageToken:
      description: If specified, an opaque token used to fetch the next page of results.
      type: string
      example: eyJsaW1pd
    Layout:
      x-schema-name: Layout
      description: Layout type of the table or view.
      type: string
      enum:
      - default
      - areaChart
      - barChart
      - bubbleChart
      - calendar
      - card
      - detail
      - form
      - ganttChart
      - lineChart
      - masterDetail
      - pieChart
      - scatterChart
      - slide
      - wordCloud
      x-tsEnumNames:
      - Default
      - AreaChart
      - BarChart
      - BubbleChart
      - Calendar
      - Card
      - Detail
      - Form
      - GanttChart
      - LineChart
      - MasterDetail
      - PieChart
      - ScatterChart
      - Slide
      - WordCloud
    SortDirection:
      x-schema-name: SortDirection
      description: Direction of a sort for a table or view.
      type: string
      enum:
      - ascending
      - descending
      x-tsEnumNames:
      - Ascending
      - Descending
    ColumnReference:
      x-schema-name: ColumnReference
      description: Reference to a column.
      type: object
      required:
      - id
      - type
      - href
      additionalProperties: false
      properties:
        id:
          type: string
          description: ID of the column.
          example: c-tuVwxYz
        type:
          type: string
          description: The type of this resource.
          enum:
          - column
          x-tsType: Type.Column
        href:
          type: string
          format: url
          description: API link to the column.
          example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/tables/grid-pqRst-U/columns/c-tuVwxYz
    SortBy:
      x-schema-name: SortBy
      description: Determines how the objects returned are sorted
      type: string
      enum:
      - name
      x-tsEnumNames:
      - Name
    Table:
      x-schema-name: Table
      description: Metadata about a table.
      type: object
      required:
      - id
      - type
      - tableType
      - href
      - name
      - parent
      - browserLink
      - displayColumn
      - rowCount
      - sorts
      - layout
      - createdAt
      - updatedAt
      - viewId
      additionalProperties: false
      properties:
        id:
          type: string
          description: ID of the table.
          example: grid-pqRst-U
        type:
          type: string
          description: The type of this resource.
          enum:
          - table
          x-tsType: Type.Table
        tableType:
          $ref: '#/components/schemas/TableType'
        href:
          type: string
          format: url
          description: API link to the table.
          example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/tables/grid-pqRst-U
        browserLink:
          type: string
          format: url
          description: Browser-friendly link to the table.
          example: https://docs.superhuman.com/d/_dAbCDeFGH/#Teams-and-Tasks_tpqRst-U
        name:
          type: string
          description: Name of the table.
          example: Tasks
        parent:
          $ref: '#/components/schemas/PageReference'
        parentTable:
          $ref: '#/components/schemas/TableReference'
        displayColumn:
          $ref: '#/components/schemas/ColumnReference'
        rowCount:
          type: integer
          description: Total number of rows in the table.
          example: 130
        sorts:
          type: array
          description: Any sorts applied to the table.
          items:
            $ref: '#/components/schemas/Sort'
        layout:
          $ref: '#/components/schemas/Layout'
        filter:
          allOf:
          - description: Detailed information about the filter formula for the table, if applicable.
            additionalProperties: false
          - $ref: '#/components/schemas/FormulaDetail'
        createdAt:
          type: string
          format: date-time
          description: Timestamp for when the table was created.
          example: '2018-04-11T00:18:57.946Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp for when the table was last modified.
          example: '2018-04-11T00:18:57.946Z'
    TableReference:
      x-schema-name: TableReference
      description: Reference to a table or view.
      type: object
      required:
      - id
      - type
      - tableType
      - browserLink
      - href
      - name
      additionalProperties: false
      properties:
        id:
          type: string
          description: ID of the table.
          example: grid-pqRst-U
        type:
          type: string
          description: The type of this resource.
          enum:
          - table
          x-tsType: Type.Table
        tableType:
          $ref: '#/components/schemas/TableType'
        href:
          type: string
          format: url
          description: API link to the table.
          example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/tables/grid-pqRst-U
        browserLink:
          type: string
          format: url
          description: Browser-friendly link to the table.
          example: https://docs.superhuman.com/d/_dAbCDeFGH/#Teams-and-Tasks_tpqRst-U
        name:
          type: string
          description: Name of the table.
          example: Tasks
        parent:
          $ref: '#/components/schemas/PageReference'
    TableType:
      x-schema-name: TableType
      type: string
      enum:
      - table
      - view
      x-tsEnumNames:
      - Table
      - View
    FormulaDetail:
      x-schema-name: FormulaDetail
      description: Detailed information about a formula.
      type: object
      required:
      - valid
      additionalProperties: false
      properties:
        valid:
          type: boolean
          description: Returns whether or not the given formula is valid.
          example: true
        isVolatile:
          type: boolean
          description: 'Returns whether or not the given formula can return different results in different contexts (for example, for different users).

            '
          example: false
        hasUserFormula:
          type: boolean
          description: Returns whether or not the given formula has a User() formula within it.
          example: false
        hasTodayFormula:
          type: boolean
          description: Returns whether or not the given formula has a Today() formula within it.
          example: false
        hasNowFormula:
          type: boolean
          description: Returns whether or not the given formula has a Now() formula within it.
          example: false
  responses:
    TooManyRequestsError:
      description: The client has sent too many requests.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 429
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Too Many Requests
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Too Many Requests
    NotFoundError:
      description: The resource could not be located with the current API token.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 404
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Not Found
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Not Found
    UnauthorizedError:
      description: The API token is invalid or has expired.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 401
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Unauthorized
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Unauthorized
    ForbiddenError:
      description: The API token does not grant access to this resource.
      content:
        application/json:
          schema:
            description: An HTTP error resulting from an unsuccessful request.
            required:
            - statusCode
            - statusMessage
            - message
            additionalProperties: false
            properties:
              statusCode:
                type: number
                description: HTTP status code of the error.
                example: 403
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Forbidden
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Forbidden
  securitySchemes:
    Bearer:
      description: "The Superhuman Docs API can be accessed using an API token, which can be obtained from [*My account*](https://docs.superhuman.com/account)\nin Superhuman Docs. This token should be specified by setting a header as follows.\n\n```Authorization: Bearer <api_token>```\n\nKeep your token safe, as anyone who gets access to it can access your account. Once a token is created\nit cannot be viewed or modified, so don't lose it.\n\nIf you're logged into Superhuman Docs, you can also query the API directly using your browser. Note that only GET\nendpoints are supported; for anything else, you'll have to use Bearer authentication.\n\n### Restricting token authorization\n\nBy default, bearer tokens created for the Superhuman Docs API can perform any action that the user who created the token\ncan perform. However, Superhuman Docs API bearer tokens can also be created with restrictions. These restrictions\ncan limit what objects can be operated on and the types of operations that can be performed.\n\n#### Operation types\n\nThe table below describes the types of authorization restrictions that can be placed on a Superhuman Docs API token.\n<table>\n  <tr><th>Restriction</th><th>Description</th><th>Allowed HTTP Methods</th></tr>\n  <tr>\n    <td>Read access</td>\n    <td>Allows access to API methods that read the state of an object</td>\n    <td>GET</td>\n  </tr>\n  <tr>\n    <td>Write access</td>\n    <td>Allows access to API methods that write the state of an object</td>\n    <td>POST, PUT, DELETE</td>\n  </tr>\n  <tr>\n    <td>Read and write access</td>\n    <td>Allows access to all methods for an object</td>\n    <td>All</td>\n  </tr>\n</table>\n\n#### Object types\n\nSuperhuman Docs API tokens can be restricted to the following types of objects.\n\n* Documents: Restricts access to only allow API calls for `/docs/${DOC_ID}`\n* Tables: Restricts access to only allow API calls for `/docs/${DOC_ID}/tables/${TABLE_ID}`\n\n#### Special cases\n\nThere are a few special case methods that violate the above restrictions.\n\n* `/whoami`: This method can be called by all Superhuman Docs API tokens.\n* `/resolveBrowserLink`: This method can be called by all Superhuman Docs API tokens, but will only return a result\nif the token has access (read or write) to the object referenced by the URL.\n\n#### Feedback\n\nThis feature is under development and we'd love to hear your feedback and bug reports. Please\nvisit us at the [Developers Central](https://connect.superhuman.com/c/developers-central) forum within\nthe Superhuman Community.\n"
      type: http
      scheme: bearer
      bearerFormat: UUID
x-tagGroups:
- name: Folders
  tags:
  - Folders
- name: Docs
  tags:
  - Docs
  - Permissions
  - Publishing
- name: Doc Structure
  tags:
  - Pages
  - Automations
- name: Tables and Views
  tags:
  - Tables
  - Columns
  - Rows
- name: Formulas & Controls
  tags:
  - Formulas
  - Controls
- name: Miscellaneous
  tags:
  - Account
  - Analytics
  - Miscellaneous