HubSpot Folders API

openapi: 3.2.0
info:
  title: Hubspot Folders API
  x-refined-note:
  - x-hubspot-api-use-case differs across the merged source definitions and was not carried
  - x-hubspot-introduction differs across the merged source definitions and was not carried
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
  version: '1.0'
  description: 'Operations tagged Folders across 2 of this provider''s published API definitions: hubspot-cms-pages-openapi.json, hubspot-files-files-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.hubapi.com
tags:
- name: Folders
paths:
  /cms/pages/2026-09/landing-pages/folders:
    get:
      tags:
      - Folders
      summary: Get all landing page folders
      description: Get the list of Landing Page Folders. Supports paging and filtering. This method would be useful for an integration that examined these models and used an external service to suggest edits.
      operationId: get-/cms/pages/2026-09/landing-pages/folders_getFoldersPage
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: createdAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAfter
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedBefore
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalContentFolderForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
      - oauth2:
        - content.landing_pages.read
    post:
      tags:
      - Folders
      summary: Create a landing page folder
      description: Create a new folder for landing pages.
      operationId: post-/cms/pages/2026-09/landing-pages/folders_createFolder
      parameters: []
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/ContentFolder'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentFolder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content.landing_pages.write
      - oauth2:
        - content
    servers:
    - url: https://api.hubapi.com
  /cms/pages/2026-09/landing-pages/folders/batch/read:
    post:
      tags:
      - Folders
      summary: Retrieve folders
      description: Retrieve a batch of landing page folders as identified in the request body.
      operationId: post-/cms/pages/2026-09/landing-pages/folders/batch/read_readFolders
      parameters:
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/BatchInputString'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseContentFolder'
        '207':
          description: multiple statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseContentFolderWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
      - oauth2:
        - content.landing_pages.read
    servers:
    - url: https://api.hubapi.com
  /cms/pages/2026-09/landing-pages/folders/{objectId}:
    get:
      tags:
      - Folders
      summary: Retrieve a landing page folder
      description: Retrieve a landing page folder, specified by its ID.
      operationId: get-/cms/pages/2026-09/landing-pages/folders/{objectId}_getFolderById
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      - name: property
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentFolder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
      - oauth2:
        - content.landing_pages.read
    delete:
      tags:
      - Folders
      summary: Delete a landing page folder
      description: Delete a landing page folder, specified by its ID.
      operationId: delete-/cms/pages/2026-09/landing-pages/folders/{objectId}_archiveFolder
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content.landing_pages.write
      - oauth2:
        - content
    patch:
      tags:
      - Folders
      summary: Update a landing page folder
      description: Partially update a landing page folder, specified by the folder ID. You only need to specify the details values that you are modifying.
      operationId: patch-/cms/pages/2026-09/landing-pages/folders/{objectId}_updateFolder
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/ContentFolder'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentFolder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content.landing_pages.write
      - oauth2:
        - content
    servers:
    - url: https://api.hubapi.com
  /cms/pages/2026-09/landing-pages/folders/{objectId}/revisions:
    get:
      tags:
      - Folders
      summary: Retrieves previous versions of a folder
      description: Retrieves all the previous versions of a landing page folder.
      operationId: get-/cms/pages/2026-09/landing-pages/folders/{objectId}/revisions_getFolderPreviousVersions
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: before
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalContentFolderVersion'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
      - oauth2:
        - content.landing_pages.read
    servers:
    - url: https://api.hubapi.com
  /cms/pages/2026-09/landing-pages/folders/{objectId}/revisions/{revisionId}:
    get:
      tags:
      - Folders
      summary: Retrieve a previous version of a folder
      description: Retrieve a previous version of a folder, specified by the folder ID and revision ID.
      operationId: get-/cms/pages/2026-09/landing-pages/folders/{objectId}/revisions/{revisionId}_getFolderPreviousVersion
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: revisionId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentFolderVersion'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content
      - oauth2:
        - content.landing_pages.read
    servers:
    - url: https://api.hubapi.com
  /cms/pages/2026-09/landing-pages/folders/{objectId}/revisions/{revisionId}/restore:
    post:
      tags:
      - Folders
      summary: Restore a previous version of a folder
      description: Takes a specified version of a landing page folder and restores it.
      operationId: post-/cms/pages/2026-09/landing-pages/folders/{objectId}/revisions/{revisionId}/restore_restoreFolderPreviousVersion
      parameters:
      - name: objectId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: revisionId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentFolder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - content.landing_pages.write
      - oauth2:
        - content
    servers:
    - url: https://api.hubapi.com
  /files/2026-03/folders/search:
    get:
      tags:
      - Folders
      summary: Search folders
      description: Search for folders. Does not contain hidden or archived folders.
      operationId: get-/files/2026-03/folders/search_doSearch
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: before
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: createdAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAtGte
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: createdAtLte
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: idGte
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: idLte
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int64
      - name: ids
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
            format: int64
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      - name: name
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: parentFolderIds
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: integer
            format: int64
      - name: path
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: properties
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: sort
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: updatedAt
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAtGte
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      - name: updatedAtLte
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseFolder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files
      - oauth2:
        - files.read
      - oauth2:
        - files.ui_hidden.read
    servers:
    - url: https://api.hubapi.com
  /files/2026-03/folders/update/async:
    post:
      tags:
      - Folders
      summary: Update folder properties
      description: Update properties of folder by given ID. This action happens asynchronously and will update all of the folder's children as well.
      operationId: post-/files/2026-03/folders/update/async_updatePropertiesRecursively
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderUpdateInputWithId'
        required: true
      responses:
        '202':
          description: accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderUpdateTaskLocator'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files.ui_hidden.write
      - oauth2:
        - files
      - oauth2:
        - files.write
    servers:
    - url: https://api.hubapi.com
  /files/2026-03/folders/update/async/tasks/{taskId}/status:
    get:
      tags:
      - Folders
      summary: Check folder update status
      description: Check status of folder update. Folder updates happen asynchronously.
      operationId: get-/files/2026-03/folders/update/async/tasks/{taskId}/status_checkUpdateStatus
      parameters:
      - name: taskId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderActionResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files.ui_hidden.write
      - oauth2:
        - files
      - oauth2:
        - files.write
    servers:
    - url: https://api.hubapi.com
  /files/2026-03/folders/{folderId}:
    get:
      tags:
      - Folders
      summary: Retrieve folder by ID
      description: Retrieve a folder by its ID.
      operationId: get-/files/2026-03/folders/{folderId}_getById
      parameters:
      - name: folderId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          pattern: \d+
          type: string
      - name: properties
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files
      - oauth2:
        - files.read
      - oauth2:
        - files.ui_hidden.read
    delete:
      tags:
      - Folders
      summary: Delete folder by ID
      description: Delete folder by ID.
      operationId: delete-/files/2026-03/folders/{folderId}_archive
      parameters:
      - name: folderId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          pattern: \d+
          type: string
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files.ui_hidden.write
      - oauth2:
        - files
      - oauth2:
        - files.delete
    patch:
      tags:
      - Folders
      summary: Update folder properties by folder ID
      description: Update a folder's properties, identified by folder ID.
      operationId: patch-/files/2026-03/folders/{folderId}_updateProperties
      parameters:
      - name: folderId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          pattern: \d+
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FolderUpdateInput'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files.ui_hidden.write
      - oauth2:
        - files
      - oauth2:
        - files.write
    servers:
    - url: https://api.hubapi.com
  /files/2026-03/folders/{folderPath}:
    get:
      tags:
      - Folders
      summary: Retrieve folder by path
      description: Retrieve a folder, identified by its path.
      operationId: get-/files/2026-03/folders/{folderPath}_getByPath
      parameters:
      - name: folderPath
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          pattern: .+
          type: string
      - name: properties
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files
      - oauth2:
        - files.read
      - oauth2:
        - files.ui_hidden.read
    delete:
      tags:
      - Folders
      summary: Delete folder by path
      description: Delete a folder, identified by its path.
      operationId: delete-/files/2026-03/folders/{folderPath}_archiveByPath
      parameters:
      - name: folderPath
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          pattern: .+
          type: string
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - files.ui_hidden.write
      - oauth2:
        - files
      - oauth2:
        - files.delete
    servers:
    - url: https://api.hubapi.com
components:
  schemas:
    BatchResponseContentFolder:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          description: Time of batch operation completion.
          format: date-time
        links:
          type: object
          additionalProperties:
            type: string
          description: Links associated with batch operation.
        requestedAt:
          type: string
          description: Time of batch operation request.
          format: date-time
        results:
          type: array
          description: Results of batch operation.
          items:
            $ref: '#/components/schemas/ContentFolder'
        startedAt:
          type: string
          description: Time of batch operation start.
          format: date-time
        status:
          type: string
          description: Status of batch operation.
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
    CollectionResponseWithTotalContentFolderForwardPaging:
      required:
      - results
      - total
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          description: Collection of content folders.
          items:
            $ref: '#/components/schemas/ContentFolder'
        total:
          type: integer
          description: Total number of content folders.
          format: int32
    ContentFolder:
      required:
      - category
      - created
      - deletedAt
      - id
      - name
      - parentFolderId
      - updated
      type: object
      properties:
        category:
          type: integer
          description: The type of object this folder applies to. Should always be LANDING_PAGE.
          format: int32
        created:
          type: string
          description: The timestamp indicating when the content folder was created.
          format: date-time
        deletedAt:
          type: string
          description: The timestamp (ISO8601 format) when this content folder was deleted.
          format: date-time
        id:
          type: string
          description: The unique ID of the content folder.
        name:
          type: string
          description: The name of the folder which will show up in the app dashboard
        parentFolderId:
          type: integer
          description: The ID of the content folder this folder is nested under
          format: int64
        updated:
          type: string
          description: The timestamp indicating when the content folder was last updated.
          format: date-time
    ErrorDetail:
      required:
      - message
      type: object
      properties:
        code:
          type: string
          description: The status code associated with the error detail
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition
          example: '{missingScopes=[scope1, scope2]}'
        in:
          type: string
          description: The name of the field or parameter in which the error was found.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where appropriate
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error
      description: Represents detailed information about an error that occurred in the API. This component is used to provide additional context and specifics about errors, typically as part of an error response.
    CollectionResponseWithTotalContentFolderVersion:
      required:
      - results
      - total
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/ContentFolderVersion'
        total:
          type: integer
          format: int32
    ForwardPaging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
      description: Paging information for forward-only pagination. Contains the next page reference when more results are available; omitted or empty on the last page.
    PreviousPage:
      required:
      - before
      type: object
      properties:
        before:
          type: string
          description: A paging cursor token for retrieving previous pages.
        link:
          type: string
          description: A URL that can be used to retrieve the previous pages' results.
      description: specifies the paging information needed to retrieve the previous set of results in a paginated API response
    VersionUser:
      required:
      - email
      - fullName
      - id
      type: object
      properties:
        email:
          type: string
          description: Email address of the user.
        fullName:
          type: string
          description: First and last name of the user.
        id:
          type: string
          description: ID of the user.
    StandardError:
      required:
      - category
      - context
      - errors
      - links
      - message
      - status
      type: object
      properties:
        category:
          type: string
          description: Error category.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Error context.
        errors:
          type: array
          description: List of error details.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        id:
          type: string
          description: Error ID.
        links:
          type: object
          additionalProperties:
            type: string
          description: Error links.
        message:
          type: string
          description: Error message.
        status:
          type: string
          description: Error status.
        subCategory:
          type: object
          properties: {}
          description: Error subcategory.
      description: Ye olde error
    Error:
      required:
      - category
      - correlationId
      - message
      type: object
      properties:
        category:
          type: string
          description: The error category
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition
          example: '{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}'
        correlationId:
          type: string
          description: A unique identifier for the request. Include this value with any error reports or support tickets
          format: uuid
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        errors:
          type: array
          description: further information about the error
          items:
            $ref: '#/components/schemas/ErrorDetail'
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs containing documentation about the error or recommended remediation steps
        me

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