Coda Project Preferences API

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


    The Superhuman Docs Admin API is a RESTful API that allows programmatic access to administrative reports & capabilities within Superhuman Docs (formerly Coda).'
  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 Admin API
    href: '#'
servers:
- url: https://docs.superhuman.com/apis/admin/v1
  description: Superhuman Docs Admin API (v1)
security:
- Bearer: []
tags:
- name: Preferences
  description: Import preferences control how external entities are imported (exempt, owner, location), scoped to an organization and importer.
paths:
  /organizations/{organizationId}/importers/{importerId}/preferences:
    get:
      summary: List import preferences
      description: Returns import preferences for the importer.
      operationId: listImportPreferences
      tags:
      - Preferences
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/importerId'
      - $ref: '#/components/parameters/importEntityIds'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: List of import preferences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportPreferenceList'
        '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: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences' |\n  jq .items[0].id\n# => List import preferences\n"
    post:
      summary: Create an import preference
      description: Creates an import preference for the importer.
      operationId: addImportPreference
      tags:
      - Preferences
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/importerId'
      requestBody:
        description: Parameters for the new import preference.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddImportPreferenceRequest'
      responses:
        '200':
          description: Confirmation that the import preference was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportPreferenceMutationResult'
        '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 = 'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences'\npayload = {\n  'externalEntity': {'id': 'folder-abc123', 'type': 'folder'},\n  'preferenceType': 'exempt',\n}\nres = requests.post(uri, headers=headers, json=payload)\n\n# => Create an import preference\n"
      - label: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' -X POST \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences' \\\n  -d '{\"externalEntity\": {\"id\": \"folder-abc123\", \"type\": \"folder\"}, \"preferenceType\": \"exempt\"}'\n# => Create an import preference\n"
  /organizations/{organizationId}/importers/{importerId}/preferences/{importPreferenceId}:
    get:
      summary: Get an import preference
      description: Returns the requested import preference.
      operationId: getImportPreference
      tags:
      - Preferences
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/importerId'
      - $ref: '#/components/parameters/importPreferenceId'
      responses:
        '200':
          description: The requested import preference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportPreference'
        '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: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences/<your import preference id>' |\n  jq .id\n# => Get an import preference\n"
    put:
      summary: Update an import preference
      description: Replaces the preference type and settings for the existing import preference. The request body must match the target `preferenceType` variant; omitted fields are not preserved across types.
      operationId: updateImportPreference
      tags:
      - Preferences
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/importerId'
      - $ref: '#/components/parameters/importPreferenceId'
      requestBody:
        description: Parameters for the import preference.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateImportPreferenceRequest'
      responses:
        '200':
          description: Confirmation that the import preference was updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportPreferenceMutationResult'
        '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: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' -X PUT \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences/<your import preference id>' \\\n  -d '{\"preferenceType\": \"exempt\"}'\n# => Update an import preference\n"
    delete:
      summary: Delete an import preference
      description: Deletes the import preference.
      operationId: removeImportPreference
      tags:
      - Preferences
      parameters:
      - $ref: '#/components/parameters/organizationId'
      - $ref: '#/components/parameters/importerId'
      - $ref: '#/components/parameters/importPreferenceId'
      responses:
        '200':
          description: The import preference was deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteImportPreferenceResult'
        '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: Shell
        lang: shell
        source: "curl -s -H 'Authorization: Bearer <your API token>' -X DELETE \\\n  'https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences/<your import preference id>'\n# => Delete an import preference\n"
components:
  schemas:
    AddLocationImportPreferenceRequest:
      x-schema-name: AddLocationImportPreferenceRequest
      description: Create a location import preference.
      type: object
      required:
      - externalEntity
      - preferenceType
      - externalParent
      additionalProperties: false
      properties:
        externalEntity:
          $ref: '#/components/schemas/ImportExternalEntity'
        preferenceType:
          type: string
          enum:
          - location
        externalParent:
          $ref: '#/components/schemas/ImportExternalParent'
    DeleteImportPreferenceResult:
      x-schema-name: DeleteImportPreferenceResult
      description: The result of deleting an import preference.
      type: object
      additionalProperties: false
      properties: {}
    AddImportPreferenceRequest:
      x-schema-name: AddImportPreferenceRequest
      description: Create an import preference.
      oneOf:
      - $ref: '#/components/schemas/AddExemptImportPreferenceRequest'
      - $ref: '#/components/schemas/AddOwnerImportPreferenceRequest'
      - $ref: '#/components/schemas/AddLocationImportPreferenceRequest'
      discriminator:
        propertyName: preferenceType
        mapping:
          exempt: '#/components/schemas/AddExemptImportPreferenceRequest'
          owner: '#/components/schemas/AddOwnerImportPreferenceRequest'
          location: '#/components/schemas/AddLocationImportPreferenceRequest'
    UpdateOwnerImportPreferenceRequest:
      x-schema-name: UpdateOwnerImportPreferenceRequest
      description: Update to an owner import preference.
      type: object
      required:
      - preferenceType
      - ownerEmail
      additionalProperties: false
      properties:
        preferenceType:
          type: string
          enum:
          - owner
        ownerEmail:
          type: string
          format: email
          maxLength: 512
          description: 'Email of the user who will own imported documents for this item. The address domain must be registered to the organization. The user does not need to exist yet when the preference is saved. Stored lowercased.

            '
          example: owner@example.com
    AddExemptImportPreferenceRequest:
      x-schema-name: AddExemptImportPreferenceRequest
      description: Create an exempt import preference.
      type: object
      required:
      - externalEntity
      - preferenceType
      additionalProperties: false
      properties:
        externalEntity:
          $ref: '#/components/schemas/ImportExternalEntity'
        preferenceType:
          type: string
          enum:
          - exempt
    NextPageToken:
      description: If specified, an opaque token used to fetch the next page of results.
      type: string
      example: eyJsaW1pd
    AddOwnerImportPreferenceRequest:
      x-schema-name: AddOwnerImportPreferenceRequest
      description: Create an owner import preference.
      type: object
      required:
      - externalEntity
      - preferenceType
      - ownerEmail
      additionalProperties: false
      properties:
        externalEntity:
          $ref: '#/components/schemas/ImportExternalEntity'
        preferenceType:
          type: string
          enum:
          - owner
        ownerEmail:
          type: string
          format: email
          maxLength: 512
          description: 'Email of the user who will own imported documents for this item. The address domain must be registered to the organization. The user does not need to exist yet when the preference is saved. Stored lowercased.

            '
          example: owner@example.com
    ImportExternalEntity:
      x-schema-name: ImportExternalEntity
      type: object
      description: External item this preference applies to.
      required:
      - id
      - type
      additionalProperties: false
      properties:
        id:
          type: string
          maxLength: 128
          description: 'ID of the item in the source system. For Quip, this is the `secret_path` from the Quip API.

            '
          example: thread-def456
        type:
          type: string
          maxLength: 32
          description: 'Type of the item in the source system. Allowed values depend on the importer; for Quip this must be either `thread` or `folder`.

            '
          example: thread
    UpdateExemptImportPreferenceRequest:
      x-schema-name: UpdateExemptImportPreferenceRequest
      description: Update to an exempt import preference.
      type: object
      required:
      - preferenceType
      additionalProperties: false
      properties:
        preferenceType:
          type: string
          enum:
          - exempt
    ImportExternalParent:
      x-schema-name: ImportExternalParent
      type: object
      description: Destination in the source system.
      required:
      - id
      - type
      additionalProperties: false
      properties:
        id:
          type: string
          maxLength: 128
          description: 'ID of the parent in the source system. For Quip, this is the folder''s `secret_path` from the Quip API.

            '
          example: folder-xyz789
        type:
          type: string
          description: Parent container type.
          enum:
          - folder
          example: folder
    UpdateLocationImportPreferenceRequest:
      x-schema-name: UpdateLocationImportPreferenceRequest
      description: Update to a location import preference.
      type: object
      required:
      - preferenceType
      - externalParent
      additionalProperties: false
      properties:
        preferenceType:
          type: string
          enum:
          - location
        externalParent:
          $ref: '#/components/schemas/ImportExternalParent'
    NextPageLink:
      description: If specified, a link that can be used to fetch the next page of results.
      type: string
      format: url
    ImportPreference:
      x-schema-name: ImportPreference
      description: An import preference for an external entity.
      type: object
      required:
      - type
      - id
      - externalEntity
      - preferenceType
      - createdAt
      - createdBy
      additionalProperties: false
      properties:
        type:
          type: string
          description: The type of this resource.
          enum:
          - importPreference
          x-tsType: Type.ImportPreference
        id:
          type: string
          format: uuid
          description: ID of the import preference.
          example: afe84ebf-4d06-44c5-b545-a8af5036bebf
        externalEntity:
          $ref: '#/components/schemas/ImportExternalEntity'
        preferenceType:
          type: string
          description: How the item should be treated on import.
          enum:
          - exempt
          - owner
          - location
          example: owner
        preferenceDetail:
          description: 'Settings for owner or location preferences. Omitted for exempt. On create and update, the equivalent fields are sent at the top level of the request body instead.

            '
          oneOf:
          - type: object
            required:
            - ownerEmail
            additionalProperties: false
            properties:
              ownerEmail:
                type: string
                format: email
                maxLength: 512
                description: Email of the user who will own imported documents for this item.
                example: owner@example.com
          - type: object
            required:
            - externalParent
            additionalProperties: false
            properties:
              externalParent:
                $ref: '#/components/schemas/ImportExternalParent'
        createdAt:
          type: string
          format: date-time
          description: When the preference was created, in ISO 8601 format.
          example: '2024-01-15T10:00:00.000Z'
        createdBy:
          type: number
          description: Coda user id that created the preference.
          example: 12345
        updatedAt:
          type: string
          format: date-time
          description: When the preference was last modified, in ISO 8601 format. Omitted if never updated.
          example: '2024-06-02T08:30:00.000Z'
        updatedBy:
          type: number
          description: Coda user id that last modified the preference. Omitted if never updated.
          example: 67890
    ImportPreferenceList:
      x-schema-name: ImportPreferenceList
      description: List of import preferences.
      type: object
      required:
      - items
      - href
      additionalProperties: false
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ImportPreference'
        href:
          type: string
          format: url
          description: API link to these results
          example: https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences
        nextPageToken:
          $ref: '#/components/schemas/NextPageToken'
        nextPageLink:
          allOf:
          - $ref: '#/components/schemas/NextPageLink'
          - type: string
            example: https://docs.superhuman.com/apis/admin/v1/organizations/<your organization id>/importers/quip/preferences?pageToken=eyJsaW1pd
    UpdateImportPreferenceRequest:
      x-schema-name: UpdateImportPreferenceRequest
      description: 'Replace the import preference''s type and settings. The body must match the target `preferenceType` shape (not a partial patch). The external entity is fixed at create time and cannot be changed.

        '
      oneOf:
      - $ref: '#/components/schemas/UpdateExemptImportPreferenceRequest'
      - $ref: '#/components/schemas/UpdateOwnerImportPreferenceRequest'
      - $ref: '#/components/schemas/UpdateLocationImportPreferenceRequest'
      discriminator:
        propertyName: preferenceType
        mapping:
          exempt: '#/components/schemas/UpdateExemptImportPreferenceRequest'
          owner: '#/components/schemas/UpdateOwnerImportPreferenceRequest'
          location: '#/components/schemas/UpdateLocationImportPreferenceRequest'
    ImportPreferenceMutationResult:
      x-schema-name: ImportPreferenceMutationResult
      description: The result of creating or updating an import preference.
      type: object
      required:
      - id
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: ID of the import preference.
          example: afe84ebf-4d06-44c5-b545-a8af5036bebf
  parameters:
    organizationId:
      name: organizationId
      description: ID of the organization.
      in: path
      required: true
      example: org-AbCDeFGHIj
      schema:
        type: string
    pageToken:
      name: pageToken
      description: An opaque token used to fetch the next page of results.
      in: query
      example: eyJsaW1pd
      schema:
        type: string
    importPreferenceId:
      name: importPreferenceId
      description: ID of the import preference.
      in: path
      required: true
      example: afe84ebf-4d06-44c5-b545-a8af5036bebf
      schema:
        type: string
        format: uuid
    importEntityIds:
      name: importEntityIds
      description: 'Comma-separated list of external entity ids to filter by (batch lookup). For Quip, each id is a `secret_path` from the Quip API.

        '
      in: query
      required: false
      explode: false
      example: folder-abc123,thread-def456
      schema:
        type: array
        items:
          type: string
          maxLength: 128
    importerId:
      name: importerId
      description: 'Importer id for the source system.

        '
      in: path
      required: true
      example: quip
      schema:
        type: string
        enum:
        - quip
        maxLength: 32
    limit:
      name: limit
      description: Maximum number of results to return in this query.
      in: query
      example: 10
      schema:
        type: integer
        minimum: 1
        default: 100
        maximum: 500
  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
    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
    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
  securitySchemes:
    Bearer:
      description: 'The Superhuman Docs Admin API can be accessed using an API token, which can be obtained from [*My account*](https://docs.superhuman.com/account)

        in Superhuman Docs. This token should be specified by setting a header as follows.


        ```Authorization: Bearer <api_token>```


        Keep your token safe, as anyone who gets access to it can access your account. Once a token is created

        it cannot be viewed or modified, so don''t lose it.

        '
      type: http
      scheme: bearer
      bearerFormat: UUID
x-tagGroups:
- name: API Tokens
  tags:
  - API Tokens
- name: Docs
  tags:
  - Docs
  - Doc Permissions
  - Doc Export
- name: Doc Structure
  tags:
  - Pages
- name: Events
  tags:
  - Events
- name: Folders
  tags:
  - Folders
  - Folder Permissions
- name: Groups
  tags:
  - Groups
- name: Import
  tags:
  - Preferences
- name: LegalHolds
  tags:
  - LegalHolds
- name: Organizations
  tags:
  - Organizations
  - Organization Users
  - Pack Controls
  - Pack Configurations
- name: Packs
  tags:
  - Packs
- name: Webhooks
  tags:
  - Webhooks
- name: Workspaces
  tags:
  - Workspaces
  - Workspace Users