Lucid Folders Collaboration API

openapi: 3.2.0
info:
  title: Lucid REST Folders Collaboration API
  version: '1.0'
  description: The Lucid REST API provides programmatic access to manage documents, users, folders, sharing, licensing, and audit logs across the Lucid Suite (Lucidchart, Lucidspark, and Lucidscale). Authenticate via OAuth 2.0 or API key.
  contact:
    name: Lucid Developer Platform
    url: https://developer.lucid.co/
  x-documentation: https://developer.lucid.co/reference/api
servers:
- url: https://api.lucid.co
tags:
- name: Folders Collaboration
  description: Manage user, group, and team collaborator access on folders, including granting, updating, and revoking collaboration roles.
paths:
  /v1/folders/{id}/shares/users/{userId}:
    get:
      summary: Get Folder User Collaborator
      description: Retrieves information about a specific user's direct collaborator access to a given folder. A user having access to a folder through one of the folder's ancestors will not be shown through this API.
      operationId: getFolderUserCollaborators
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderReadonly
      - OAuth2:
        - folder:readonly
      parameters:
      - in: path
        name: id
        required: true
        description: ID of the folder.
        schema:
          type: number
      - in: path
        name: userId
        required: true
        description: ID of the user to retrieve collaborator settings for.
        schema:
          type: number
      responses:
        '200':
          description: OK with a Folder User Collaborator Resource containing information about the user's collaboration settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderUserCollaborator'
        '403':
          description: Forbidden if the app making the request does not have permission to the folder, or if the folder has been deleted, or does not exist.
        '404':
          description: Not Found when a user with the specified ID cannot be found or does not have collaborator access to the folder.
    put:
      summary: Create/Update Folder User Collaborator
      description: Updates or establishes a user's collaborator access to a given folder. If the user does not already have access, a new Folder User Collaborator Resource is created. Collaborators cannot be given the role "owner", and the role of the folder's owner cannot be modified.
      operationId: putFolderUserCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderEdit
      - OAuth2:
        - folder
      parameters:
      - in: path
        name: id
        required: true
        description: ID of the folder.
        schema:
          type: number
      - in: path
        name: userId
        required: true
        description: ID of the user whose role to create or modify.
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                  - editandshare
                  - edit
                  - comment
                  - view
                  example: comment
                  description: The Collaborator Role to assign to the user for this folder.
      responses:
        '200':
          description: OK when updating an existing Folder User Collaborator. Contains the updated Folder User Collaborator Resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderUserCollaborator'
        '201':
          description: Created when creating a new Folder User Collaborator. Contains the new Folder User Collaborator Resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderUserCollaborator'
        '400':
          description: Bad Request when trying to add or update a Folder User Collaborator to have the "owner" role.
        '403':
          description: Forbidden if the token does not have permission to the folder, or if the folder has been deleted or does not exist.
    delete:
      summary: Delete Folder User Collaborator
      description: Revokes a user's direct collaborator access to a given folder. The user may still have access to the folder through other means such as shared folders. This action cannot be used to revoke access from the folder owner.
      operationId: deleteFolderUserCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderEdit
      - OAuth2:
        - folder
      parameters:
      - in: path
        name: id
        required: true
        description: ID of the folder.
        schema:
          type: number
      - in: path
        name: userId
        required: true
        description: ID of the user to delete collaborator settings for.
        schema:
          type: number
      responses:
        '204':
          description: No Content when the user's collaborator record on the folder was successfully deleted.
        '400':
          description: Bad Request when removing the user would leave a project folder without an owner. Promote another user to owner on the project first, then retry.
        '403':
          description: Forbidden * if the token does not have permission to the folder, or if the folder has been deleted or does not exist. * when attempting to revoke the collaboration for the folder owner.
  /v1/folders/{id}/shares/users:
    get:
      summary: List Folder User Collaborators
      description: Retrieves all users who have direct collaborator access to a given folder. A user having access to a folder through one of the folder's ancestors will not be shown through this API. Results are paginated.
      operationId: listFolderUserCollaborators
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderReadonly
      - OAuth2:
        - folder:readonly
      parameters:
      - in: path
        name: id
        required: true
        description: ID of the folder.
        schema:
          type: number
      responses:
        '200':
          description: OK with an array of Folder User Collaborator Resources for the folder's collaborators.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FolderUserCollaborator'
        '403':
          description: Forbidden if the token does not have permission to the folder, or if the folder has been deleted or does not exist.
  /v1/folders/{id}/shares/groups/{groupId}:
    get:
      summary: Get Folder Group Collaborator
      description: Retrieves information about a group's direct collaborator access to a given folder. A group having access to a folder through one of the folder's ancestors will not be shown through this API.
      operationId: getFolderGroupCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderReadonly
      - OAuth2:
        - folder
        - folder:readonly
      parameters:
      - in: path
        name: id
        required: true
        description: Folder ID.
        schema:
          type: number
      - in: path
        name: groupId
        required: true
        description: Group ID.
        schema:
          type: number
      responses:
        '200':
          description: OK with a Folder Group Collaborator Resource containing information about the group's collaboration access on the folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderGroupCollaborator'
        '403':
          description: Forbidden if the token does not have access to the folder, or if the folder has been deleted or does not exist.
        '404':
          description: Not Found when the group does not have direct collaborator access to the folder.
    put:
      summary: Create/Update Folder Group Collaborator
      description: Grants a group direct collaborator access to a given folder, or updates the group's role on the folder if it is already a collaborator.
      operationId: updateFolderGroupCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderEdit
      - OAuth2:
        - folder
      parameters:
      - in: path
        name: id
        required: true
        description: Folder ID.
        schema:
          type: number
      - in: path
        name: groupId
        required: true
        description: Group ID.
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                  - editandshare
                  - edit
                  - comment
                  - view
                  example: comment
                  description: The Collaborator Role to assign to the group for this folder.
      responses:
        '200':
          description: OK when updating an existing Folder Group Collaborator. Contains the updated Folder Group Collaborator Resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderGroupCollaborator'
        '201':
          description: Created when creating a new Folder Group Collaborator. Contains the new Folder Group Collaborator Resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderGroupCollaborator'
        '400':
          description: Bad Request when trying to add or update a Folder Group Collaborator to have the "owner" role.
        '403':
          description: Forbidden if the token does not have permission to the folder, or if the folder or group have been deleted or do not exist.
    delete:
      summary: Delete Folder Group Collaborator
      description: Revokes any direct collaborator access a group has to the given folder.
      operationId: deleteFolderGroupCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderEdit
      - OAuth2:
        - folder
      parameters:
      - in: path
        name: id
        required: true
        description: Folder ID.
        schema:
          type: number
      - in: path
        name: groupId
        required: true
        description: Group ID.
        schema:
          type: number
      responses:
        '204':
          description: No Content when the group's collaborator record on the folder was successfully deleted.
        '400':
          description: Bad Request when removing the group would leave a project folder without an owner.
        '403':
          description: Forbidden if the token does not have permission to the folder, or if the folder has been deleted or does not exist.
  /v1/folders/{id}/shares/groups:
    get:
      summary: List Folder Group Collaborators
      description: Retrieves all groups that have been granted direct collaborator access to a given folder. A group having access to a folder through one of the folder's ancestors will not be shown through this API. Results are paginated.
      operationId: listFolderGroupCollaborators
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderReadonly
      - OAuth2:
        - folder
        - folder:readonly
      parameters:
      - in: path
        name: id
        required: true
        description: Folder ID.
        schema:
          type: number
      responses:
        '200':
          description: OK with an array of Folder Group Collaborator Resources containing the folder's collaborators, as well as Pagination headers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FolderGroupCollaborator'
        '403':
          description: Forbidden if the token does not have access to the folder, or if the folder has been deleted or does not exist.
  /v1/folders/{id}/shares/teams/{teamId}:
    get:
      summary: Get Folder Team Collaborator
      description: Returns information about the given team's collaboration on the given folder.
      operationId: getFolderTeamCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderReadonly
      - OAuth2:
        - folder:readonly
      parameters:
      - in: path
        name: id
        required: true
        description: ID of the folder.
        schema:
          type: number
      - in: path
        name: teamId
        required: true
        description: ID of the team to retrieve collaborator settings for.
        schema:
          type: number
        example: 99
      responses:
        '200':
          description: OK with a Folder Team Collaborator Resource containing information about the team's collaboration access on the folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderTeamCollaborator'
        '403':
          description: Forbidden when the app making the request does not have permission for the folder, or if the folder has been deleted or does not exist.
        '404':
          description: Not Found when a team with the specified ID cannot be found or does not have collaborator access to the folder.
    put:
      summary: Create/Update Folder Team Collaborator
      description: Updates the details of the given team's collaboration on the given folder, or adds the team as a collaborator on the folder if it is not already a collaborator.
      operationId: putFolderTeamCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderEdit
      - OAuth2:
        - folder
      parameters:
      - in: path
        name: id
        required: true
        description: ID of the folder.
        schema:
          type: number
      - in: path
        name: teamId
        required: true
        description: ID of the team whose role is to be created or modified.
        schema:
          type: number
        example: 99
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                  - editandshare
                  - edit
                  - comment
                  - view
                  example: comment
                  description: The Collaborator Role to assign to the team for this folder.
      responses:
        '200':
          description: OK when updating an existing Folder Team Collaborator. Contains the updated Folder Team Collaborator Resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderTeamCollaborator'
        '201':
          description: Created when creating a new Folder Team Collaborator. Contains the new Folder Team Collaborator Resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderTeamCollaborator'
        '400':
          description: Bad Request when trying to add or update a collaborator to have the "owner" role.
        '403':
          description: Forbidden when the token does not have permission for the folder, or if the folder has been deleted or does not exist.
    delete:
      summary: Delete Folder Team Collaborator
      description: Revokes a team's direct collaborator access to the given folder.
      operationId: deleteFolderTeamCollaborator
      tags:
      - Folders Collaboration
      security:
      - ApiKey:
        - FolderEdit
      - OAuth2:
        - folder
      parameters:
      - in: path
        name: id
        required: true
        description: ID of the folder.
        schema:
          type: number
      - in: path
        name: teamId
        required: true
        description: ID of the team to delete collaborator settings for.
        schema:
          type: number
        example: 99
      responses:
        '204':
          description: No Content when the team's collaborator record on the folder was successfully deleted.
        '400':
          description: Bad Request when removing the team would leave a project folder without an owner.
        '403':
          description: Forbidden if the token does not have permission to the folder, or if the folder has been deleted or does not exist.
components:
  schemas:
    FolderTeamCollaborator:
      type: object
      properties:
        folderId:
          type: integer
          description: Folder ID
        teamId:
          type: integer
          description: Team ID
        role:
          $ref: '#/components/schemas/Role'
        created:
          type: string
          format: date-time
          description: Date and time when the collaboration was created
      required:
      - folderId
      - teamId
      - role
      - created
    FolderUserCollaborator:
      type: object
      properties:
        folderId:
          type: integer
          description: Folder ID
        userId:
          type: integer
          description: User ID
        role:
          $ref: '#/components/schemas/Role'
        created:
          type: string
          format: date-time
          description: Date and time when the collaboration was created
      required:
      - folderId
      - userId
      - role
      - created
    FolderGroupCollaborator:
      type: object
      properties:
        folderId:
          type: integer
          description: Folder ID
        groupId:
          type: integer
          description: Group ID
        role:
          $ref: '#/components/schemas/Role'
        created:
          type: string
          format: date-time
          description: Date and time when the collaboration was created
      required:
      - folderId
      - groupId
      - role
      - created
    Role:
      type: string
      enum:
      - owner
      - editandshare
      - edit
      - comment
      - view
      description: The Collaborator Role on the document or folder
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://lucid.app/oauth2/authorize
          tokenUrl: https://api.lucid.co/oauth2/token
          refreshUrl: https://api.lucid.co/oauth2/token
          scopes:
            account.audit.logs: View audit logs on your account.
            account.info: View basic information about your account (e.g., account ID and account name) .
            account.user: Create, view, edit, and delete users on your account.
            account.user:readonly: View users on your account.
            account.users:admin.readonly: View all users and their roles on your account.
            account.user.transfercontent: Transfer ownership of a user's resources to another user on your account.
            account.settings:readonly: View settings on your account.
            account.legalhold: Create, view, and expire legal holds on your account.
            account.legalhold:readonly: View legal holds on your account.
            account.legalhold.users: Manage legal hold users on your account.
            account.legalhold.users:readonly: View legal hold users on your account.
            folder: Create, view, edit, share, and delete your folders. Organize your folders and their contents.
            folder:readonly: View any of your folders and list their contents.
            folder:admin: Perform admin actions on folders belonging to the account.
            folder:admin.readonly: View all folders belonging to the account with admin permissions.
            invitation: Accept document and folder share links.
            invitation.accept: Accept document and folder share links.
            cloud.credential: Manage cloud credentials.
            cloud.credential:readonly: View cloud credentials.
            cloud.datasource: Manage cloud data sources.
            cloud.datasource:readonly: View cloud data sources.
            cloud.model: Manage cloud models.
            repository: Manage repositories.
            repository:readonly: View repositories.
            repository:admin: Perform admin actions on repositories.
            lucid.document.content: Create, view, edit, and delete any Lucid document accessible by the user.
            lucid.document.content:readonly: View and download any Lucid document accessible by the user.
            lucid.document.content:admin: Perform admin actions on Lucid documents belonging to the account.
            lucid.document.content:admin.readonly: View all Lucid documents belonging to the account with admin permissions.
            lucid.document.content.share: Create, view, edit, and delete document collaborators, embeds, and share links for any Lucid document accessible by the user.
            lucid.document.content.share:readonly: View document collaborators, embeds, and share links for any Lucid document accessible by the user.
            lucid.document.content.share.collaborator: Create, view, edit, and delete document collaborators for any Lucid document accessible by the user.
            lucid.document.content.share.collaborator:readonly: View document collaborators for any Lucid document accessible by the user.
            lucid.document.content.share.embed: Create, view, edit, and delete document embeds for any Lucid document accessible by the user.
            lucid.document.content.share.embed:readonly: View document embeds for any Lucid document accessible by the user.
            lucid.document.content.share.link: Create, view, edit, and delete share links for any Lucid document accessible by the user.
            lucid.document.content.share.link:readonly: View share links for any Lucid document accessible by the user.
            lucid.document.storage:admin.readonly: Perform admin actions backing up Lucid documents belonging to the account.
            lucid.document.app: View, edit, create, and manage folders and documents within an app.
            lucid.document.app.folder: Create, view, edit, and manage any Lucid document within its app-specific folder.
            lucid.document.app.picker: View, edit, and manage any Lucid document selected within an app.
            lucid.document.app.picker:readonly: View and download any Lucid document selected within an app.
            lucid.document.app.picker.share: Create, view, edit, and delete document collaborators, embeds, and share links for any Lucid document selected within an app.
            lucid.document.app.picker.share:readonly: View document collaborators, embeds, and share links for any Lucid document selected within an app.
            lucid.document.app.picker.share.collaborator: Create, view, edit, and delete document collaborators for any Lucid document selected within an app.
            lucid.document.app.picker.share.collaborator:readonly: View document collaborators for any Lucid document selected within an app.
            lucid.document.app.picker.share.embed: Create, view, edit, and delete document embeds for any Lucid document selected within an app.
            lucid.document.app.picker.share.embed:readonly: View document embeds for any Lucid document selected within an app.
            lucid.document.app.picker.share.link: Create, view, edit, and delete share links for any Lucid document selected within an app.
            lucid.document.app.picker.share.link:readonly: View share links for any Lucid document selected within an app.
            lucid.document.accessRequest: Request access to Lucid documents.
            licenses:admin: Perform admin actions on licenses and subscriptions belonging to the account.
            licenses:admin.readonly: View licenses and subscriptions belonging to the account with admin permissions.
            teams: Create, view, and edit, archive, and restore any teams on your account. Control which users belong to teams.
            teams:readonly: View any teams on your account and list which users belong to them.
            teams:admin: Manage teams on your account.
            lucidchart.document.app: View, edit, and manage any Lucidchart document selected for this third-party application. Create, view, edit, and manage any Lucidchart document within its app-specific folder.
            lucidchart.document.app.folder: Create, view, edit, and manage any Lucidchart document within its app-specific folder.
            lucidchart.document.app.picker: View, edit, and manage any Lucidchart document selected for this third-party application.
            lucidchart.document.app.picker:readonly: View and download any Lucidchart document selected for this third-party application.
            lucidchart.document.app.picker.share: Create, view, edit, and delete document collaborators, embeds, and share links for any Lucidchart document selected for this third-party application.
            lucidchart.document.app.picker.share:readonly: View document collaborators, embeds, and share links for any Lucidchart document selected for this third-party application.
            lucidchart.document.app.picker.share.collaborator: Create, view, edit, and delete collaborators and invitations of any Lucidchart document on your team or enterprise account selected for the third-party application.
            lucidchart.document.app.picker.share.collaborator:readonly: View collaborators and invitations of any Lucidchart document on your team or enterprise account selected for the third-party application.
            lucidchart.document.app.picker.share.embed: Create, view, edit, and delete embeds of any Lucidchart document on your team or enterprise account selected for the third-party application.
            lucidchart.document.app.picker.share.embed:readonly: View embeds of any Lucidchart document on your team or enterprise account selected for the third-party application.
            lucidchart.document.app.picker.share.link: Create, view, edit, and delete the third party application's share links of any Lucidchart document on your team or enterprise account selected for the third-party application.
            lucidchart.document.app.picker.share.link:readonly: View the third party application's share links of any Lucidchart document on your team or enterprise account selected for the third-party application.
            lucidchart.document.content: Create, view, edit, and delete any Lucidchart document on your account.
            lucidchart.document.content:readonly: View and download any Lucidchart document on your account.
            lucidchart.document.content:admin: Perform admin actions on Lucidchart documents belonging to the account.
            lucidchart.document.content:admin.readonly: View all Lucidchart documents belonging to the account with admin permissions.
            lucidchart.document.content.share: Create, view, edit, and delete document collaborators, embeds, and share links for any of your Lucidchart documents.
            lucidchart.document.content.share:readonly: View document collaborators, embeds, and share links for any of your Lucidchart documents.
            lucidchart.document.content.share.collaborator: Create, view, edit, and delete collaborators and invitations for any of your Lucidchart documents on your team or enterprise account.
            lucidchart.document.content.share.collaborator:readonly: View collaborators and invitations for any of your Lucidchart documents on your team or enterprise account.
            lucidchart.document.content.share.embed: Create, view, edit, and delete embeds for any of your Lucidchart documents on your team or enterprise account.
            lucidchart.document.content.share.embed:readonly: View embeds for any of your Lucidchart documents on your team or enterprise account.
            lucidchart.document.content.share.link: Create, view, edit, and delete the third party application's share links for any of your Lucidchart documents on your team or enterprise account.
            lucidchart.document.content.share.link:readonly: View the third party application's share links for any of your Lucidchart documents on your team or enterprise account.
            lucidchart.document.storage:admin.readonly: Perform admin actions backing up Lucidchart documents belonging to the account.
            lucidchart.document.accessRequest: Request access to Lucidchart documents.
            lucidspark.document.app: View, edit, and manage any Lucidspark board selected for this third-party application. Create, view, edit, and manage any Lucidspark board within its app-specific folder.
            lucidspark.document.app.folder: Create, view, edit, and manage any Lucidspark board within its app-specific folder.
            lucidspark.document.app.picker: View, edit, and manage any Lucidspark board selected for this third-party application.
            lucidspark.document.app.picker:readonly: View and download any Lucidspark board selected for this third-party application.
            lucidspark.document.app.picker.share: Create, view, edit, and delete document collaborators, embeds, and share links for any Lucidspark board selected for this third-party application.
            lucidspark.document.app.picker.share:readonly: View document collaborators, embeds, and share links for any Lucidspark board selected for this third-party application.
            lucidspark.document.app.picker.share.collaborator: Create, view, edit, and delete collaborators and invitations of any Lucidspark board on your team or enterprise account selected for the third-party application.
            lucidspark.document.app.picker.share.collaborator:readonly: View collaborators and invitations of any Lucidspark board on your team or enterprise account selected for the third-party application.
            lucidspark.document.app.picker.share.embed: Create, view, edit, and delete embeds of any Lucidspark board on your team or enterprise account selected for the third-party application.
            lucidspark.document.app.picker.share.embed:readonly: View embeds of any Lucidspark board on your team or enterprise account selected for the third-party application.
            lucidspark.document.app.picker.share.link: Create, view, edit, and delete the third party application's share links of any Lucidspark board on your team or enterprise account selected for the third-party application.
            lucidspark.document.app.picker.share.link:readonly: View the third party application's share links of any Lucidspark board on your team or enterprise account selected for the third-party application.
            lucidspark.document.content: Create, view, edit, and delete any Lucidspark board on your account.
            lucidspark.document.content:readonly: View and download any Lucidspark board on your account.
            lucidspark.document.content:admin: Perform admin actions on Lucidspark boards belonging to the account.
            lucidspark.document.content:admin.readonly: View all Lucidspark boards belonging to the account with admin permissions.
            lucidspark.document.content.share: Create, view, edit, and delete document collaborators, embeds, and share links for any of your Lucidspark boards.
            lucidspark.document.content.share:readonly: View document collaborators, embeds, and share links for any of your Lucidspark boards.
            lucidspark.document.content.share.collaborator: Create, view, edit, and delete collaborators and invitations for any of your Lucidspark boards on your team or enterprise account.
            lucidspark.document.content.share.collaborator:readonly: View collaborators and invitations for any of your Lucidspark boards on your team or enterprise account.
            lucidspark.document.content.share.embed: Create, view, edit, and delete embeds for any of your Lucidspark boards on your team or enterprise account.
            lucidspark.document.content.share.embed:readonly: View embeds for any of your Lucidspark boards on your team or enterprise account.
            lucidspark.docume

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lucid/refs/heads/main/openapi/lucid-folders-collaboration-api-openapi.yml