openapi: 3.1.0
info:
  title: WD My Cloud Home API
  description: >-
    The WD My Cloud Home REST API enables off-device applications to manage
    files and folders on a user's My Cloud Home NAS device. It supports file
    upload, download, listing, search, sharing, thumbnails, and device
    discovery via OAuth 2.0 authentication.
  version: v2
  termsOfService: https://www.westerndigital.com/legal/terms-of-use
  contact:
    name: Western Digital Developer Support
    url: https://developer.westerndigital.com/develop/wd-my-cloud-home/forms.html
  license:
    name: Western Digital Developer Terms
    url: https://developer.westerndigital.com/develop/wd-my-cloud-home/
servers:
  - url: https://config.mycloud.com
    description: Configuration service — call first to get device and auth URLs
  - url: https://device.mycloud.com
    description: Device service (dynamically resolved per device)
  - url: https://wdc.auth0.com
    description: Authentication service

tags:
  - name: Configuration
    description: Retrieve dynamic service endpoint configuration.
  - name: Authentication
    description: OAuth 2.0 authorization and token operations.
  - name: Files
    description: File and folder CRUD operations.
  - name: Search
    description: Search files by parent directory.
  - name: Sharing
    description: Create and manage file shares.
  - name: User
    description: User account information.
  - name: Device
    description: Device registration and discovery.

paths:
  /config/v1/config:
    get:
      operationId: getServiceConfiguration
      summary: Get Service Configuration
      description: >-
        Returns all service endpoint URLs used by My Cloud Home applications,
        including device, auth, and network service URLs. Applications must call
        this endpoint first to resolve dynamic service URLs before making
        subsequent API calls.
      tags:
        - Configuration
      responses:
        '200':
          description: Service configuration object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceConfiguration'
              example:
                data:
                  cloud:
                    service:
                      urls:
                        componentMap:
                          service.device.url: "https://device.mycloud.com"
                          service.devicenetwork.url: "https://devicenetwork.mycloud.com"
                          service.auth0.url: "https://wdc.auth0.com"
                          service.auth.url: "https://auth.mycloud.com"

  /authorize:
    get:
      operationId: authorizeUser
      summary: Authorize User
      description: >-
        Initiates the OAuth 2.0 authorization code flow. Redirects the user
        to the WD authentication page.
      tags:
        - Authentication
      servers:
        - url: https://wdc.auth0.com
      parameters:
        - name: client_id
          in: query
          required: true
          schema:
            type: string
          description: OAuth 2.0 client identifier.
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
            format: uri
          description: URI to redirect to after authorization.
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum: [code]
          description: Must be "code" for authorization code flow.
        - name: scope
          in: query
          required: false
          schema:
            type: string
          description: >-
            Space-separated list of scopes. Supported:
            openid, email, profile, nas_read_only, nas_read_write.
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: CSRF protection state parameter.
      responses:
        '302':
          description: Redirect to authorization page.

  /oauth/token:
    post:
      operationId: getAccessToken
      summary: Get Access Token
      description: >-
        Exchange authorization code for an OAuth 2.0 access token. Also
        supports refresh_token grant type when offline_access scope was
        requested.
      tags:
        - Authentication
      servers:
        - url: https://wdc.auth0.com
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [authorization_code, refresh_token]
                  description: OAuth 2.0 grant type.
                code:
                  type: string
                  description: Authorization code from the redirect.
                client_id:
                  type: string
                  description: OAuth 2.0 client identifier.
                client_secret:
                  type: string
                  description: OAuth 2.0 client secret.
                redirect_uri:
                  type: string
                  description: Redirect URI matching the original request.
                refresh_token:
                  type: string
                  description: Refresh token (for refresh_token grant).
              required: [grant_type, client_id, client_secret]
      responses:
        '200':
          description: Access token response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'

  /userinfo:
    get:
      operationId: getUserInfo
      summary: Get User Information
      description: Returns profile information for the authenticated user.
      tags:
        - User
      servers:
        - url: https://wdc.auth0.com
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User profile information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: Unauthorized.

  /authservice/v2/auth0/user:
    get:
      operationId: getAuthUser
      summary: Get Authenticated User
      description: Returns the authenticated user's account details from the auth service.
      tags:
        - User
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Authenticated user details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAccount'
        '401':
          description: Unauthorized.

  /device/v1/user:
    get:
      operationId: getUserDevices
      summary: List User Devices
      description: Returns all My Cloud Home devices associated with the authenticated user.
      tags:
        - Device
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of devices associated with the user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceListResponse'
        '401':
          description: Unauthorized.

  /device/v1/device:
    get:
      operationId: getDevice
      summary: Get Device Details
      description: Returns details about a specific My Cloud Home device.
      tags:
        - Device
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Device details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          description: Unauthorized.

  /sdk/v2/files:
    get:
      operationId: listFiles
      summary: List Files
      description: >-
        Returns a paginated list of files and folders within a directory on the
        My Cloud Home device. Use "root" as the folder ID to list the root
        directory.
      tags:
        - Files
      security:
        - bearerAuth: []
      parameters:
        - name: ids
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated list of file IDs to retrieve.
        - name: pageToken
          in: query
          required: false
          schema:
            type: string
          description: Token for pagination to retrieve the next page.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            maximum: 100
          description: Maximum number of results to return.
      responses:
        '200':
          description: List of files and folders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilesResponse'
        '401':
          description: Unauthorized.

    post:
      operationId: createFile
      summary: Create File
      description: >-
        Uploads a new file or creates a folder on the My Cloud Home device.
        Supports multipart/related for simultaneous metadata and content upload.
      tags:
        - Files
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileCreateRequest'
          multipart/related:
            schema:
              type: object
              properties:
                metadata:
                  $ref: '#/components/schemas/FileCreateRequest'
                content:
                  type: string
                  format: binary
      responses:
        '201':
          description: File or folder created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileItem'
        '401':
          description: Unauthorized.

  /sdk/v2/files/{fileId}:
    get:
      operationId: getFile
      summary: Get File
      description: Returns metadata for a specific file or folder.
      tags:
        - Files
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the file or folder.
      responses:
        '200':
          description: File metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileItem'
        '404':
          description: File not found.

    patch:
      operationId: updateFile
      summary: Update File
      description: Updates metadata for a file or folder (e.g., rename, move).
      tags:
        - Files
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the file or folder.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUpdateRequest'
      responses:
        '200':
          description: Updated file metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileItem'
        '404':
          description: File not found.

    delete:
      operationId: deleteFile
      summary: Delete File
      description: Permanently deletes a file or folder from the device.
      tags:
        - Files
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the file or folder.
      responses:
        '204':
          description: File deleted.
        '404':
          description: File not found.

  /sdk/v2/files/{fileId}/content:
    get:
      operationId: downloadFile
      summary: Download File Content
      description: Downloads the content of a specific file.
      tags:
        - Files
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the file.
      responses:
        '200':
          description: File content.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: File not found.

    put:
      operationId: uploadFileContent
      summary: Upload File Content
      description: Uploads or replaces the content of an existing file.
      tags:
        - Files
      security:
        - bearerAuth: []
      parameters:
        - name: fileId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the file.
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: File content updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileItem'

  /sdk/v2/filesSearch/parents:
    get:
      operationId: searchFilesByParent
      summary: Search Files by Parent
      description: Returns files within a specified parent folder, enabling directory traversal.
      tags:
        - Search
      security:
        - bearerAuth: []
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: string
          description: >-
            Comma-separated list of parent folder IDs to search within.
            Use "root" for the root folder.
        - name: pageToken
          in: query
          required: false
          schema:
            type: string
          description: Pagination token.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
            maximum: 100
          description: Maximum number of results.
      responses:
        '200':
          description: Files within the specified parent folder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilesResponse'
        '401':
          description: Unauthorized.

  /v1/shares:
    post:
      operationId: createShare
      summary: Create Share
      description: Creates a share link for one or more files on the device.
      tags:
        - Sharing
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareCreateRequest'
            example:
              ownerId: "user123"
              deviceId: "device456"
              fileIds: ["file789", "file101"]
      responses:
        '201':
          description: Share created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
        '401':
          description: Unauthorized.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 Bearer token obtained via the /oauth/token endpoint.
        Include in Authorization header as "Bearer {token}".

  schemas:
    ServiceConfiguration:
      type: object
      description: Dynamic service endpoint configuration.
      properties:
        data:
          type: object
          properties:
            cloud:
              type: object
              properties:
                service:
                  type: object
                  properties:
                    urls:
                      type: object
                      properties:
                        componentMap:
                          type: object
                          additionalProperties:
                            type: string

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: OAuth 2.0 access token.
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          description: Token lifetime in seconds.
        refresh_token:
          type: string
          description: Refresh token (if offline_access scope requested).
        id_token:
          type: string
          description: OpenID Connect ID token.
        scope:
          type: string
          description: Space-separated list of granted scopes.
      required: [access_token, token_type, expires_in]

    UserInfo:
      type: object
      properties:
        sub:
          type: string
          description: Subject identifier (user ID).
        email:
          type: string
          format: email
        name:
          type: string
        picture:
          type: string
          format: uri

    UserAccount:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        username:
          type: string

    Device:
      type: object
      properties:
        id:
          type: string
          description: Unique device identifier.
        name:
          type: string
          description: User-defined device name.
        model:
          type: string
          description: Device model name.
        internalURI:
          type: string
          format: uri
          description: Device endpoint for same-network access.
        externalURI:
          type: string
          format: uri
          description: Device endpoint for remote access.
        status:
          type: string
          description: Device online/offline status.

    DeviceListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Device'

    FileItem:
      type: object
      properties:
        id:
          type: string
          description: Unique file/folder identifier.
        name:
          type: string
          description: File or folder name.
        mimeType:
          type: string
          description: MIME type. Use "application/x.wd.dir" for folders.
        size:
          type: integer
          description: File size in bytes.
        parentId:
          type: string
          description: ID of the parent folder. "root" for top-level items.
        createdTime:
          type: string
          format: date-time
        modifiedTime:
          type: string
          format: date-time
        thumbnailUrl:
          type: string
          format: uri
          description: URL for image/video thumbnail.
        downloadUrl:
          type: string
          format: uri
          description: Direct download URL.

    FilesResponse:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileItem'
        pageToken:
          type: string
          description: Token for the next page of results. Absent if no more pages.

    FileCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the file or folder.
        mimeType:
          type: string
          description: MIME type. Use "application/x.wd.dir" to create a folder.
        parentId:
          type: string
          description: Parent folder ID. Use "root" for root directory.
      required: [name, mimeType, parentId]

    FileUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: New name for the file or folder.
        parentId:
          type: string
          description: New parent folder ID (to move the file).

    ShareCreateRequest:
      type: object
      properties:
        ownerId:
          type: string
          description: Owner user ID.
        deviceId:
          type: string
          description: Device ID where the files reside.
        fileIds:
          type: array
          items:
            type: string
          description: List of file IDs to share.
        expirationDate:
          type: string
          format: date-time
          description: Optional share expiration date.
      required: [ownerId, deviceId, fileIds]

    Share:
      type: object
      properties:
        id:
          type: string
          description: Unique share identifier.
        shareUrl:
          type: string
          format: uri
          description: Public URL for the share.
        ownerId:
          type: string
        deviceId:
          type: string
        fileIds:
          type: array
          items:
            type: string
        createdTime:
          type: string
          format: date-time
        expirationDate:
          type: string
          format: date-time