Coda Publishing API

openapi: 3.2.0
info:
  version: 1.5.0
  title: Coda Publishing 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: Publishing
  description: Coda docs can be published publicly and associated with categories to help the world discover them. This API lets you manage the publishing settings of your docs.
paths:
  /categories:
    get:
      summary: Get doc categories
      description: Gets all available doc categories.
      operationId: listCategories
      tags:
      - Publishing
      responses:
        '200':
          description: List of doc categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocCategoryList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '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://coda.io/apis/v1/categories''

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


          print(f''Category count: {res["categories"].length}'')

          # => Category count: 10

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://coda.io/apis/v1/categories' |\n  jq .categories.name\n# => \"10\"\n"
      - label: Google Apps Script
        lang: javascript
        source: '// Import the CodaAPI library via Resource->Libraries...:

          // 15IQuWOk8MqT50FDWomh57UqWGH23gjsWVWYFms3ton6L-UHmefYHS9Vl

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

          var categories = CodaAPI.listCategories();

          Logger.log(''Category count: '' + categories.categories.length);

          // => Category count: 10

          '
  /docs/{docId}/publish:
    put:
      summary: Publish doc
      description: Update publish settings for a doc.
      operationId: publishDoc
      tags:
      - Publishing
      parameters:
      - $ref: '#/components/parameters/docId'
      requestBody:
        description: Parameters for changing publish settings.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocPublish'
      responses:
        '202':
          description: Confirmation that the publish request was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishResult'
        '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\n\nheaders = {'Authorization': 'Bearer <your API token>'}\nuri = f'https://coda.io/apis/v1/docs/<doc ID>/publish'\npayload = {\n  'discoverable': true,\n}\nreq = requests.put(uri, headers=headers, json=payload)\nreq.raise_for_status() # Throw if there was an error.\nres = req.json()\n\nprint(f'Discoverable will be true')\n# => Discoverable will be true\n"
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' -X POST -H \"Content-Type: application/json\" \\\n  -d '{\"discoverable\": true}' \\\n  'https://coda.io/apis/v1/docs/<doc ID>/publish'\n  # => Will be discoverable\n"
      - label: Google Apps Script
        lang: javascript
        source: '// Import the CodaAPI library via Resource->Libraries...:

          // 15IQuWOk8MqT50FDWomh57UqWGH23gjsWVWYFms3ton6L-UHmefYHS9Vl

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

          var res = CodaAPI.publishDoc(<doc ID>, {discoverable: true});

          Logger.log(''Discoverable will be true'');

          // => Discoverable will be true

          '
    delete:
      summary: Unpublish doc
      description: Unpublishes a doc.
      operationId: unpublishDoc
      tags:
      - Publishing
      parameters:
      - $ref: '#/components/parameters/docId'
      responses:
        '200':
          description: A result indicating that the doc was unpublished.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnpublishResult'
        '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://coda.io/apis/v1/docs/<doc ID>/publish''

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

          '
      - label: Shell
        lang: shell
        source: "curl -s -X DELETE -H 'Authorization: Bearer <your API token>' \\\n  'https://coda.io/apis/v1/docs/<doc ID>/unpublish' |\n"
      - label: Google Apps Script
        lang: javascript
        source: '// Import the CodaAPI library via Resource->Libraries...:

          // 15IQuWOk8MqT50FDWomh57UqWGH23gjsWVWYFms3ton6L-UHmefYHS9Vl

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

          var docInfo = CodaAPI.unpublishDoc(''<doc ID>'');

          // => The given doc is now unpublished

          '
components:
  schemas:
    DocPublish:
      x-schema-name: DocPublish
      description: Payload for publishing a doc or or updating its publishing information.
      type: object
      additionalProperties: false
      properties:
        slug:
          type: string
          description: Slug for the published doc.
          example: my-doc
        discoverable:
          type: boolean
          description: If true, indicates that the doc is discoverable.
          example: true
        earnCredit:
          type: boolean
          description: 'If true, new users may be required to sign in to view content within this document. You will receive Coda credit for each user who signs up via your doc.

            '
          example: true
        categoryNames:
          type: array
          description: The names of categories to apply to the document.
          example:
          - Project management
          items:
            type: string
        mode:
          $ref: '#/components/schemas/DocPublishMode'
    DocPublishMode:
      x-schema-name: DocPublishMode
      description: Which interaction mode the published doc should use.
      type: string
      enum:
      - view
      - play
      - edit
      x-tsEnumNames:
      - View
      - Play
      - Edit
    DocCategoryList:
      x-schema-name: DocCategoryList
      type: object
      description: A list of categories that can be applied to a doc.
      required:
      - items
      additionalProperties: false
      properties:
        items:
          type: array
          description: Categories for the doc.
          items:
            $ref: '#/components/schemas/DocCategory'
    PublishResult:
      x-schema-name: PublishResult
      description: The result of publishing a doc.
      allOf:
      - $ref: '#/components/schemas/DocumentMutateResponse'
      - type: object
        additionalProperties: false
        properties: {}
    DocumentMutateResponse:
      x-schema-name: DocumentMutateResponse
      description: Base response type for an operation that mutates a document.
      type: object
      additionalProperties: false
      required:
      - requestId
      properties:
        requestId:
          type: string
          description: An arbitrary unique identifier for this request.
          example: abc-123-def-456
    UnpublishResult:
      x-schema-name: UnpublishResult
      description: The result of unpublishing a doc.
      type: object
      additionalProperties: false
      properties: {}
    DocCategory:
      x-schema-name: DocCategory
      type: object
      description: The category applied to a doc.
      required:
      - name
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the category.
          example: Project Management
  parameters:
    docId:
      name: docId
      description: ID of the doc.
      in: path
      required: true
      example: AbCDeFGH
      schema:
        type: string
  responses:
    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
    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
    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
    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
  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