Coda Project CustomDocDomains API

openapi: 3.2.0
info:
  version: 1.5.0
  title: Superhuman Docs Custom Doc Domains 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: CustomDocDomains
paths:
  /docs/${docId}/domains:
    get:
      summary: List custom doc domains
      description: List all custom domains for a published doc.
      operationId: listCustomDocDomains
      tags:
      - CustomDocDomains
      parameters:
      - $ref: '#/components/parameters/docId'
      responses:
        '200':
          description: List of custom domains for a published doc.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDocDomainList'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
    post:
      summary: Add custom domain
      description: Add a custom domain to a published doc.
      operationId: addCustomDocDomain
      tags:
      - CustomDocDomains
      parameters:
      - $ref: '#/components/parameters/docId'
      requestBody:
        description: Parameters for adding a custom domain to a published doc.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCustomDocDomainRequest'
      responses:
        '202':
          description: Confirmation that the custom domain was added to the doc.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddCustomDocDomainResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /docs/{docId}/domains/{customDocDomain}:
    delete:
      summary: Deletes a custom domain
      description: Deletes a custom domain from a published doc.
      operationId: deleteCustomDocDomain
      tags:
      - CustomDocDomains
      parameters:
      - $ref: '#/components/parameters/docId'
      - $ref: '#/components/parameters/customDocDomain'
      responses:
        '200':
          description: A result indicating that the custom domain was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomDocDomainResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
    patch:
      summary: Updates a custom domain
      description: Updates properties of a document's custom domain.
      operationId: updateCustomDocDomain
      tags:
      - CustomDocDomains
      parameters:
      - $ref: '#/components/parameters/docId'
      - $ref: '#/components/parameters/customDocDomain'
      requestBody:
        description: Properties of a custom domain to update.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomDocDomainRequest'
      responses:
        '200':
          description: The custom domain object with the updates applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCustomDocDomainResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /domains/provider/{customDocDomain}:
    get:
      summary: Gets custom doc domains providers
      description: Gets the provider (ie. GoDaddy) of a custom domain.
      operationId: getCustomDocDomainProvider
      tags:
      - CustomDocDomains
      parameters:
      - $ref: '#/components/parameters/customDocDomain'
      responses:
        '200':
          description: Provider of the custom domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDocDomainProviderResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
components:
  schemas:
    UpdateCustomDocDomainRequest:
      x-schema-name: UpdateCustomDocDomainRequest
      type: object
      description: Payload for updating the properties of a custom published doc domain.
      additionalProperties: false
      properties: {}
    CustomDocDomain:
      x-schema-name: CustomDocDomain
      type: object
      description: The custom domain added to a published doc.
      required:
      - customDocDomain
      - hasCertificate
      - hasDnsDocId
      - setupStatus
      - domainStatus
      additionalProperties: false
      properties:
        customDocDomain:
          type: string
          description: The custom domain.
          example: example.com
        hasCertificate:
          type: boolean
          description: Whether the domain has a certificate
          example: true
        hasDnsDocId:
          type: boolean
          description: Whether the domain DNS points back to this doc.
          example: true
        setupStatus:
          $ref: '#/components/schemas/CustomDocDomainSetupStatus'
        domainStatus:
          $ref: '#/components/schemas/CustomDomainConnectedStatus'
        lastVerifiedTimestamp:
          type: string
          format: date-time
          description: When the domain DNS settings were last checked.
          example: '2018-04-11T00:18:57.946Z'
    CustomDomainConnectedStatus:
      x-schema-name: CustomDomainConnectedStatus
      type: string
      enum:
      - connected
      - notConnected
      x-tsEnumNames:
      - Connected
      - NotConnected
    nextPageLink:
      description: If specified, a link that can be used to fetch the next page of results.
      type: string
      format: url
    CustomDocDomainSetupStatus:
      x-schema-name: CustomDocDomainSetupStatus
      type: string
      enum:
      - pending
      - succeeded
      - failed
      x-tsEnumNames:
      - Pending
      - Succeeded
      - Failed
    CustomDocDomainList:
      x-schema-name: CustomDocDomainList
      type: object
      description: List of all custom domains added to a published doc.
      required:
      - customDocDomains
      additionalProperties: false
      properties:
        customDocDomains:
          type: array
          description: Custom domains for the published doc.
          items:
            $ref: '#/components/schemas/CustomDocDomain'
        nextPageToken:
          $ref: '#/components/schemas/nextPageToken'
        nextPageLink:
          allOf:
          - $ref: '#/components/schemas/nextPageLink'
          - type: string
            example: https://docs.superhuman.com/apis/v1/docs/AbCDeFGH/domains?pageToken=eyJsaW1pd
    DeleteCustomDocDomainResponse:
      x-schema-name: DeleteCustomDocDomainResponse
      type: object
      description: The result of deleting a custom domain from a published doc.
      additionalProperties: false
      properties: {}
    CustomDocDomainProviderResponse:
      x-schema-name: CustomDocDomainProviderResponse
      type: object
      description: The result of determining the domain provider for a custom doc domain.
      required:
      - provider
      additionalProperties: false
      properties:
        provider:
          $ref: '#/components/schemas/CustomDocDomainProvider'
    CustomDocDomainProvider:
      x-schema-name: CustomDocDomainProvider
      type: string
      enum:
      - GoDaddy
      - Namecheap
      - Hover (Tucows)
      - Network Solutions
      - Google Domains
      - Other
      x-tsEnumNames:
      - GoDaddy
      - Namecheap
      - Hover
      - NetworkSolutions
      - GoogleDomains
      - Other
    AddCustomDocDomainResponse:
      x-schema-name: AddCustomDocDomainResponse
      type: object
      description: The result of adding a custom domain to a published doc.
      additionalProperties: false
      properties: {}
    UpdateCustomDocDomainResponse:
      x-schema-name: UpdateCustomDocDomainResponse
      type: object
      description: The result of updating a custom domain for a published doc.
      additionalProperties: false
      properties: {}
    AddCustomDocDomainRequest:
      x-schema-name: AddCustomDocDomainRequest
      type: object
      description: Payload for adding a custom published doc domain.
      required:
      - customDocDomain
      additionalProperties: false
      properties:
        customDocDomain:
          type: string
          description: The custom domain.
          example: example.com
    nextPageToken:
      description: If specified, an opaque token used to fetch the next page of results.
      type: string
      example: eyJsaW1pd
  responses:
    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
    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
    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
  parameters:
    customDocDomain:
      name: customDocDomain
      description: A custom domain for a published doc.
      in: path
      required: true
      schema:
        type: string
    docId:
      name: docId
      description: ID of the doc.
      in: path
      required: true
      example: AbCDeFGH
      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