Coda Folders API

openapi: 3.2.0
info:
  version: 1.5.0
  title: Coda Folders API
  license:
    name: Coda Developer Terms
    url: https://coda.io/trust/developer
  description: '# Introduction


    The Coda API is a RESTful API that lets you programmatically interact with Coda docs:


    * List and search Coda docs

    * 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 Coda with an AI tool, you may also want to consider using the

    Coda MCP server.'
  termsOfService: https://coda.io/trust/tos
  contact:
    name: API Support
    url: https://coda.io
    email: help+api@coda.io
  x-logo:
    url: https://cdn.coda.io/external/img/apilogo.png
    backgroundColor: transparent
    altText: Coda API
    href: '#'
servers:
- url: https://coda.io/apis/v1
  description: Coda API (v1)
security:
- Bearer: []
tags:
- name: Folders
  description: Folders help you organize your docs within workspaces. This API lets you list, create, update, and delete folders.
paths:
  /folders:
    get:
      summary: List folders
      description: Returns a list of folders the user has access to.
      operationId: listFolders
      tags:
      - Folders
      parameters:
      - name: workspaceId
        in: query
        description: Show only folders belonging to the given workspace.
        schema:
          type: string
        example: ws-1Ab234
      - name: isStarred
        in: query
        description: If true, returns folders that are starred. If false, returns folders that are not starred. If not specified, returns all folders.
        schema:
          type: boolean
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: List of folders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderList'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: "import requests\n\nheaders = {'Authorization': 'Bearer <your API token>'}\nuri = 'https://coda.io/apis/v1/folders'\nres = requests.get(uri, headers=headers).json()\n\nfor folder in res['items']:\n    print(f'Folder: {folder[\"name\"]}')\n"
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://coda.io/apis/v1/folders' |\n  jq '.items[].name'\n"
    post:
      summary: Create folder
      description: Creates a new folder.
      operationId: createFolder
      tags:
      - Folders
      requestBody:
        description: Parameters for creating the folder.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderRequest'
      responses:
        '201':
          description: The created folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: 'import requests


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

          uri = ''https://coda.io/apis/v1/folders''

          payload = {''name'': ''My New Folder''}

          res = requests.post(uri, headers=headers, json=payload).json()


          print(f''Created folder: {res["id"]}'')

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\": \"My New Folder\"}' \\\n  'https://coda.io/apis/v1/folders' |\n  jq .id\n"
  /folders/{folderId}:
    get:
      summary: Get folder
      description: Returns the requested folder.
      operationId: getFolder
      tags:
      - Folders
      parameters:
      - $ref: '#/components/parameters/folderId'
      responses:
        '200':
          description: The requested Coda folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '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 = ''https://coda.io/apis/v1/folders/<your folder id>''

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


          print(f''Folder name is: {res["name"]}'')

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://coda.io/apis/v1/folders/<your folder id>' |\n  jq .name\n"
    patch:
      summary: Update folder
      description: Updates metadata for a folder.
      operationId: updateFolder
      tags:
      - Folders
      parameters:
      - $ref: '#/components/parameters/folderId'
      requestBody:
        description: Parameters for updating the folder.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFolderRequest'
      responses:
        '200':
          description: The updated folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '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 = ''https://coda.io/apis/v1/folders/<your folder id>''

          payload = {''name'': ''Updated Folder Name''}

          res = requests.patch(uri, headers=headers, json=payload).json()


          print(f''Updated folder: {res["name"]}'')

          '
      - label: Shell
        lang: shell
        source: "curl -s -X PATCH -H 'Authorization: Bearer <your API token>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\": \"Updated Folder Name\"}' \\\n  'https://coda.io/apis/v1/folders/<your folder id>' |\n  jq .name\n"
    delete:
      summary: Delete folder
      description: Deletes a folder. The folder must be empty (contain no docs).
      operationId: deleteFolder
      tags:
      - Folders
      parameters:
      - $ref: '#/components/parameters/folderId'
      responses:
        '200':
          description: Folder was successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFolderResult'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '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 = ''https://coda.io/apis/v1/folders/<your folder id>''

          res = requests.delete(uri, headers=headers)


          print(f''Deleted: {res.status_code == 200}'')

          '
      - label: Shell
        lang: shell
        source: "curl -s -X DELETE -H 'Authorization: Bearer <your API token>' \\\n  'https://coda.io/apis/v1/folders/<your folder id>'\n"
components:
  schemas:
    Folder:
      x-schema-name: Folder
      description: A Coda folder.
      type: object
      required:
      - id
      - type
      - name
      - browserLink
      - workspace
      additionalProperties: false
      properties:
        id:
          type: string
          description: ID of the Coda folder.
          example: fl-1Ab234
        type:
          type: string
          description: The type of this resource.
          enum:
          - folder
          x-tsType: Type.Folder
        name:
          type: string
          description: The name of the folder.
          example: Projects
        browserLink:
          type: string
          format: url
          description: Browser-friendly link to the folder.
          example: https://coda.io/folders/fl-1Ab234
        description:
          type: string
          description: The description of the folder.
          example: A collection of project docs.
        icon:
          $ref: '#/components/schemas/Icon'
        createdAt:
          type: string
          format: date-time
          description: Timestamp for when the folder was created.
          example: '2018-04-11T00:18:57.946Z'
        canEdit:
          type: boolean
          description: Whether the folder settings can be edited. E.g., some folder types (like personal folders - "My Docs") cannot be edited.
          example: true
        workspace:
          $ref: '#/components/schemas/WorkspaceReference'
    WorkspaceReference:
      x-schema-name: WorkspaceReference
      description: Reference to a Coda workspace.
      type: object
      required:
      - id
      - type
      - browserLink
      additionalProperties: false
      properties:
        id:
          type: string
          description: ID of the Coda workspace.
          example: ws-1Ab234
        type:
          type: string
          description: The type of this resource.
          enum:
          - workspace
          x-tsType: Type.Workspace
        organizationId:
          type: string
          description: ID of the organization bound to this workspace, if any.
          example: org-2Bc456
        browserLink:
          type: string
          format: url
          description: Browser-friendly link to the Coda workspace.
          example: https://coda.io/docs?workspaceId=ws-1Ab234
        name:
          type: string
          description: Name of the workspace; included if the user has access to the workspace.
          example: My workspace
    FolderList:
      x-schema-name: FolderList
      description: List of folders.
      type: object
      required:
      - items
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Folder'
        href:
          type: string
          format: url
          description: API link to these results.
          example: https://coda.io/apis/v1/folders?workspaceId=ws-1Ab234
        nextPageToken:
          $ref: '#/components/schemas/nextPageToken'
        nextPageLink:
          allOf:
          - $ref: '#/components/schemas/nextPageLink'
          - type: string
            example: https://coda.io/apis/v1/folders?pageToken=xyz
    CreateFolderRequest:
      x-schema-name: CreateFolderRequest
      description: Request for creating a folder.
      type: object
      required:
      - name
      - workspaceId
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the folder.
          example: Projects
        workspaceId:
          type: string
          description: ID of the workspace where the folder should be created.
          example: ws-1Ab234
        description:
          type: string
          description: Description of the folder.
          example: A collection of project docs.
    nextPageLink:
      description: If specified, a link that can be used to fetch the next page of results.
      type: string
      format: url
    Icon:
      x-schema-name: icon
      description: Info about the icon.
      type: object
      required:
      - name
      - type
      - browserLink
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the icon.
        type:
          type: string
          description: MIME type of the icon
        browserLink:
          type: string
          format: url
          description: Browser-friendly link to an icon.
          example: https://cdn.coda.io/icons/png/color/icon-32.png
    UpdateFolderRequest:
      x-schema-name: UpdateFolderRequest
      description: Request for updating a folder.
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the folder.
          example: Projects
        description:
          type: string
          description: Description of the folder.
          example: A collection of project docs.
    nextPageToken:
      description: If specified, an opaque token used to fetch the next page of results.
      type: string
      example: eyJsaW1pd
    DeleteFolderResult:
      x-schema-name: DeleteFolderResult
      description: The result of a folder deletion.
      type: object
      additionalProperties: false
  responses:
    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
    BadRequestError:
      description: The request parameters did not conform to expectations.
      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: 400
              statusMessage:
                type: string
                description: HTTP status message of the error.
                example: Bad Request
              message:
                type: string
                description: Any additional context on the error, or the same as `statusMessage` otherwise.
                example: Bad Request
    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
    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
  parameters:
    limit:
      name: limit
      description: Maximum number of results to return in this query.
      in: query
      example: 10
      schema:
        type: integer
        minimum: 1
        default: 25
    pageToken:
      name: pageToken
      description: An opaque token used to fetch the next page of results.
      in: query
      example: eyJsaW1pd
      schema:
        type: string
    folderId:
      name: folderId
      description: ID of the folder.
      in: path
      required: true
      example: fl-1Ab234
      schema:
        type: string
  securitySchemes:
    Bearer:
      description: "The Coda API can be accessed using an API token, which can be obtained from [*My account*](https://coda.io/account)\nin Coda. 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 Coda, 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 Coda API can perform any action that the user who created the token\ncan perform. However, Coda 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 Coda 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\nCoda 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 Coda API tokens.\n* `/resolveBrowserLink`: This method can be called by all Coda 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 Coda 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