HubSpot CRM Public App Feature Flags v3 API

openapi: 3.0.1
info:
  title: HubSpot CRM Public App Feature Flags v3
  description: Basepom for all HubSpot Projects
  version: 2026-09
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
servers:
- url: https://api.hubapi.com
tags:
- name: Basic
- name: Batch
paths:
  /feature-flags/2026-09/{appId}/flags/all:
    get:
      tags:
      - Basic
      operationId: get-/feature-flags/2026-09/{appId}/flags/all_/feature-flags/v3/{appId}/flags/all
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagsForAppResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-read
  /feature-flags/2026-09/{appId}/flags/{flagName}:
    get:
      tags:
      - Basic
      summary: Retrieve an app's feature flags
      description: Retrieve the current status of the app's feature flags. No request body is included.
      operationId: get-/feature-flags/2026-09/{appId}/flags/{flagName}
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-read
    put:
      tags:
      - Basic
      summary: Set an app's feature flag
      description: Set a feature flag for an app. For example, update the `hs-hide-crm-cards` flag's `defaultState`
        to `ON` to hide classic CRM cards from new installs.
      operationId: put-/feature-flags/2026-09/{appId}/flags/{flagName}
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlagPutRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-write
    delete:
      tags:
      - Basic
      summary: Delete an app's feature flag
      description: Delete a feature flag in an app.  For example, delete the `hs-release-app-cards` flag
        after all accounts have been migrated.
      operationId: delete-/feature-flags/2026-09/{appId}/flags/{flagName}
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlagResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-write
  /feature-flags/2026-09/{appId}/flags/{flagName}/portals:
    get:
      tags:
      - Basic
      summary: Retrieve accounts with a set flag state
      description: Retrieve a list of HubSpot accounts with an account-level flag setting for the specified
        app. No request body is included.
      operationId: get-/feature-flags/2026-09/{appId}/flags/{flagName}/portals
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        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
      - name: startPortalId
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalFlagStateBatchResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-read
  /feature-flags/2026-09/{appId}/flags/{flagName}/portals/batch/delete:
    post:
      tags:
      - Batch
      summary: Batch delete account flag state
      description: Delete an account-level flag state for multiple HubSpot accounts at once. Use this
        endpoint to manage flag exposure for groups of HubSpot accounts.
      operationId: post-/feature-flags/2026-09/{appId}/flags/{flagName}/portals/batch/delete
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalFlagStateBatchDeleteRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalFlagStateBatchResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-write
  /feature-flags/2026-09/{appId}/flags/{flagName}/portals/batch/upsert:
    post:
      tags:
      - Batch
      summary: Batch set account flag state
      description: Set the portal flag state for multiple HubSpot accounts at once. Use this endpoint
        to manage flag exposure for groups of HubSpot accounts.
      operationId: post-/feature-flags/2026-09/{appId}/flags/{flagName}/portals/batch/upsert
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalFlagStateBatchPutRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalFlagStateBatchResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-write
  /feature-flags/2026-09/{appId}/flags/{flagName}/portals/{portalId}:
    get:
      tags:
      - Basic
      summary: Retrieve account flag state
      description: Retrieve the account-level flag state of a specific HubSpot account.
      operationId: get-/feature-flags/2026-09/{appId}/flags/{flagName}/portals/{portalId}
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: portalId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalFlagStateResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-read
    put:
      tags:
      - Basic
      summary: Set an account flag state
      description: Specify an account-level flag state for a specific HubSpot account.
      operationId: put-/feature-flags/2026-09/{appId}/flags/{flagName}/portals/{portalId}
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: portalId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalFlagStatePutRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalFlagStateResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-write
    delete:
      tags:
      - Basic
      summary: Delete an account flag state
      description: Delete an account-level flag state for a specific HubSpot account. No request body
        is included.
      operationId: delete-/feature-flags/2026-09/{appId}/flags/{flagName}/portals/{portalId}
      parameters:
      - name: appId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      - name: flagName
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: portalId
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalFlagStateResponse'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - developers-write
components:
  schemas:
    BatchPortalEntry:
      required:
      - flagState
      - portalId
      type: object
      properties:
        flagState:
          type: string
          description: The flag state for this portal (e.g. ON or OFF)
          enum:
          - ABSENT
          - 'OFF'
          - 'ON'
        portalId:
          type: integer
          description: The ID of the portal
          format: int32
    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
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate
          example: An error occurred
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error
      description: Represents an error response returned by the API when an operation fails. This component
        is used in various endpoints to provide detailed information about the error encountered.
      example:
        message: Invalid input (details will vary based on the error)
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        category: VALIDATION_ERROR
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
    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.
    FlagPutRequest:
      required:
      - defaultState
      type: object
      properties:
        defaultState:
          type: string
          description: The state that the flag should have if there are no overrides for a particular
            portal
          enum:
          - ABSENT
          - 'OFF'
          - 'ON'
        overrideState:
          type: string
          description: A flag value that supercedes all other overrides, including portal-level values.
            Mostly used for things like emergency overrides
          enum:
          - ABSENT
          - 'OFF'
          - 'ON'
    FlagResponse:
      required:
      - appId
      - defaultState
      - flagName
      type: object
      properties:
        appId:
          type: integer
          description: The ID of the app
          format: int32
        defaultState:
          type: string
          description: The flag state for any portal that doesn't have an override value
          enum:
          - ABSENT
          - 'OFF'
          - 'ON'
        flagName:
          type: string
          description: The name of the flag
        overrideState:
          type: string
          description: An optional flag value that overrides all others for this flag name and app, including
            portal-level values
          enum:
          - ABSENT
          - 'OFF'
          - 'ON'
    FlagsForAppResponse:
      required:
      - flagsForApp
      type: object
      properties:
        flagsForApp:
          type: array
          items:
            type: string
    PortalFlagStateBatchDeleteRequest:
      required:
      - portalIds
      type: object
      properties:
        portalIds:
          type: array
          items:
            type: integer
            format: int32
    PortalFlagStateBatchPutRequest:
      required:
      - portalStates
      type: object
      properties:
        portalStates:
          type: array
          items:
            $ref: '#/components/schemas/BatchPortalEntry'
    PortalFlagStateBatchResponse:
      required:
      - portalFlagStates
      type: object
      properties:
        portalFlagStates:
          type: array
          items:
            $ref: '#/components/schemas/PortalFlagStateResponse'
    PortalFlagStatePutRequest:
      required:
      - flagState
      type: object
      properties:
        flagState:
          type: string
          description: The state that the given flag should be in for this portal
          enum:
          - ABSENT
          - 'OFF'
          - 'ON'
    PortalFlagStateResponse:
      required:
      - appId
      - flagName
      - flagState
      - portalId
      type: object
      properties:
        appId:
          type: integer
          description: The ID of the app
          format: int32
        flagName:
          type: string
          description: The name of the flag
        flagState:
          type: string
          description: The state of the flag for this portal
          enum:
          - ABSENT
          - 'OFF'
          - 'ON'
        portalId:
          type: integer
          description: The ID of the portal
          format: int32
  responses:
    Error:
      description: An error occurred.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    developer_hapikey:
      type: apiKey
      name: hapikey
      in: query
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            developers-read: ''
            developers-write: ''
    private_apps:
      type: apiKey
      name: private-app
      in: header
    private_apps_legacy:
      type: apiKey
      name: private-app-legacy
      in: header
x-hubspot-product-tier-requirements:
  marketing: FREE
  sales: FREE
  service: FREE
  cms: FREE
  commerce: FREE
  crmHub: FREE
  dataHub: FREE