Coda Project Miscellaneous API

openapi: 3.2.0
info:
  version: 1.5.0
  title: Superhuman Docs Miscellaneous 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: Miscellaneous
  description: These endpoints wouldn't fit anywhere else, but you may find them useful when working with Superhuman Docs.
paths:
  /resolveBrowserLink:
    get:
      summary: Resolve browser link
      description: Given a browser link to a Superhuman Docs object, attempts to find it and return metadata that can be used to get more info on it. Returns a 400 if the URL does not appear to be a Superhuman Docs URL or a 404 if the resource cannot be located with the current credentials.
      operationId: resolveBrowserLink
      tags:
      - Miscellaneous
      parameters:
      - name: url
        description: The browser link to try to resolve.
        in: query
        required: true
        example: https://docs.superhuman.com/d/_dAbCDeFGH/Launch-Status_sumnO
        schema:
          type: string
          format: url
      - name: degradeGracefully
        description: 'By default, attempting to resolve the Superhuman Docs URL of a deleted object will result in an error. If this flag is set, the next-available object, all the way up to the doc itself, will be resolved.

          '
        in: query
        example: true
        schema:
          type: boolean
      responses:
        '200':
          description: Metadata for the resolved resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiLink'
        '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-pack-hidden: true
      x-codeSamples:
      - label: Python 3.13
        lang: python
        source: "import requests\n\nheaders = {'Authorization': 'Bearer <your API token>'}\nuri = 'https://docs.superhuman.com/apis/v1/resolveBrowserLink'\nparams = {\n  'url': 'https://docs.superhuman.com/d/Some-Doc_d<doc ID>/#To-do-List_tu<table ID>',\n}\nres = requests.get(uri, headers=headers, params=params).json()\nresolved_uri = res[\"resource\"][\"href\"]\n\nres = requests.get(resolved_uri, headers=headers).json()\nprint(f'This link points to a {res[\"type\"]} named {res[\"name\"]}')\n# => This link points to a table named To-do List\n"
      - label: Shell
        lang: shell
        source: "RESOLVED_RESOURCE_URI=\"$(curl -s -H 'Authorization: Bearer <your API token>' \\\n  -G --data-urlencode 'url=https://docs.superhuman.com/d/Some-Doc_d<doc ID>/#To-do-List_tu<table ID>' \\\n  'https://docs.superhuman.com/apis/v1/resolveBrowserLink' |\n  jq -r '.resource.href')\"\ncurl -s -H 'Authorization: Bearer <your API token>' \\\n  \"$RESOLVED_RESOURCE_URI\" |\n  jq '\"This link points to a \" + .type + \" named \" + .name'\n# => \"This link points to a table named 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 url = ''https://docs.superhuman.com/d/Some-Doc_d<doc ID>/#To-do-List_tu<table ID>'';

          var res = SuperhumanDocs.resolveBrowserLink({url: url});

          Logger.log(''This link points to a '' + res.type + '' named '' + res.name);

          // => This link points to a table named To-do List

          '
  /mutationStatus/{requestId}:
    get:
      summary: Get mutation status
      description: Get the status for an asynchronous mutation to know whether or not it has been completed. Each API endpoint that mutates a document will return a request id that you can pass to this endpoint to check the completion status. Status information is not guaranteed to be available for more than one day after the mutation was completed. It is intended to be used shortly after the request was made.
      operationId: getMutationStatus
      tags:
      - Miscellaneous
      parameters:
      - $ref: '#/components/parameters/requestId'
      responses:
        '200':
          description: Info about the mutation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MutationStatus'
        '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 = ''https://docs.superhuman.com/apis/v1/mutationStatus/some-request-id''

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


          print(f''Request has completed? {res["completed"]}'')

          # => Request has completed? false

          '
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/v1/mutationStatus/some-request-id' |\n  jq .completed\n# => true\n"
      - label: Google Apps Script
        lang: javascript
        source: '// Import the SuperhumanDocs library via Resource->Libraries...:

          // 15IQuWOk8MqT50FDWomh57UqWGH23gjsWVWYFms3ton6L-UHmefYHS9Vl

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

          Logger.log(''Request has completed? '' + SuperhumanDocs.mutationStatus(''some-request-id'').completed);

          // => Request has completed? false

          '
components:
  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
    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
    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
  schemas:
    Type:
      x-schema-name: Type
      description: A constant identifying the type of the resource.
      type: string
      enum:
      - aclMetadata
      - aclPermissions
      - aclSettings
      - agentPackLog
      - analyticsLastUpdated
      - apiLink
      - automation
      - column
      - control
      - doc
      - customDocDomain
      - customDocDomainProvider
      - docAnalytics
      - docAnalyticsSummary
      - docAnalyticsV2
      - folder
      - formula
      - goLink
      - ingestionBatchExecution
      - ingestionExecution
      - ingestionExecutionAttempt
      - ingestionPackLog
      - ingestionParentItem
      - mutationStatus
      - pack
      - packAclPermissions
      - packAnalytics
      - packAnalyticsSummary
      - packAsset
      - packCategory
      - packConfigurationSchema
      - packFeaturedDocs
      - packFormulaAnalytics
      - packInvitation
      - packListingDraft
      - packLog
      - packMaker
      - packOauthConfig
      - packRelease
      - packReview
      - packSourceCode
      - packSystemConnection
      - packVersion
      - page
      - pageContentExport
      - pageContentExportStatus
      - principal
      - row
      - table
      - user
      - workspace
      x-tsEnumNames:
      - AclMetadata
      - AclPermissions
      - AclSettings
      - AgentPackLog
      - AnalyticsLastUpdated
      - ApiLink
      - Automation
      - Column
      - Control
      - Doc
      - CustomDocDomain
      - CustomDocDomainProvider
      - DocAnalytics
      - DocAnalyticsSummary
      - DocAnalyticsV2
      - Folder
      - Formula
      - GoLink
      - IngestionBatchExecution
      - IngestionExecution
      - IngestionExecutionAttempt
      - IngestionPackLog
      - IngestionParentItem
      - MutationStatus
      - Pack
      - PackAclPermissions
      - PackAnalytics
      - PackAnalyticsSummary
      - PackAsset
      - PackCategory
      - PackConfigurationSchema
      - PackFeaturedDocs
      - PackFormulaAnalytics
      - PackInvitation
      - PackListingDraft
      - PackLog
      - PackMaker
      - PackOauthConfig
      - PackRelease
      - PackReview
      - PackSourceCode
      - PackSystemConnection
      - PackVersion
      - Page
      - PageContentExport
      - PageContentExportStatus
      - Principal
      - Row
      - Table
      - User
      - Workspace
    MutationStatus:
      x-schema-name: MutationStatus
      description: The status of an asynchronous mutation.
      type: object
      required:
      - completed
      additionalProperties: false
      properties:
        completed:
          type: boolean
          description: Returns whether the mutation has completed.
          example: true
        warning:
          type: string
          description: A warning if the mutation completed but with caveats.
          example: Initial page HTML was invalid.
    ApiLink:
      x-schema-name: ApiLink
      description: Info about a resolved link to an API resource.
      type: object
      required:
      - type
      - href
      - resource
      additionalProperties: false
      properties:
        type:
          type: string
          description: The type of this resource.
          enum:
          - apiLink
          x-tsType: Type.ApiLink
        href:
          type: string
          format: url
          description: Self link to this query.
          example: https://docs.superhuman.com/apis/v1/resolveBrowserLink?url=https%3A%2F%2Fdocs.superhuman.com%2Fd%2F_dAbCDeFGH%2FLaunch-Status_sumnO
        browserLink:
          type: string
          format: url
          description: Canonical browser-friendly link to the resolved resource.
          example: https://docs.superhuman.com/d/_dAbCDeFGH/Launch-Status_sumnO
        resource:
          $ref: '#/components/schemas/ApiLinkResolvedResource'
    ApiLinkResolvedResource:
      x-schema-name: ApiLinkResolvedResource
      type: object
      description: Reference to the resolved resource.
      required:
      - id
      - href
      - type
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/Type'
        id:
          type: string
          description: ID of the resolved resource.
          example: canvas-IjkLmnO
        name:
          type: string
          description: Name of the resource.
          example: My Page
        href:
          type: string
          format: url
          description: API link to the resolved resource that can be queried to get further information.
          example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/pages/canvas-IjkLmnO
  parameters:
    requestId:
      name: requestId
      description: ID of the request.
      in: path
      required: true
      example: abc-123-def-456
      schema:
        type: string
  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