GrowthBook Dimensions API

openapi: 3.2.0
info:
  version: 5.1.0
  title: GrowthBook REST Dimensions API
  description: 'GrowthBook offers a full REST API for interacting with the application. Request data can use either JSON or Form data encoding (with proper `Content-Type` headers). All response bodies are JSON-encoded. The API base URL for GrowthBook Cloud is `https://api.growthbook.io/api`. For self-hosted deployments, it is the same as your API_HOST environment variable (defaults to `http://localhost:3100/api`). The rest of these docs will assume you are using GrowthBook Cloud. ## Versioning


    Endpoints are versioned by path prefix:


    - `/v1/...` — stable, widely-supported endpoints

    - `/v2/...` — updated endpoints with improved shapes (e.g. unified per-rule environment scope for feature flags)


    New integrations should prefer v2 where available. Feature-flag and metric v1 routes are deprecated: they are tagged **LEGACY** in the sidebar and collapsed by default. Use the matching v2 group when both exist. ## Authentication


    We support both the HTTP Basic and Bearer authentication schemes for convenience. You first need to generate a new API Key in GrowthBook. Different keys have different permissions:


    - **Personal Access Tokens**: These are sensitive and provide the same level of access as the user has to an organization, or less if the token''s permissions are limited. These can be created by going to `Personal Access Tokens` under your user menu. Members with the API Keys **Manage members'' tokens** permission can disable a member''s token under `Settings -> Manage PATs`, and admins can require new tokens to expire within a maximum lifetime. - **Secret Keys**: These are sensitive and provide the level of access of the role they are given, which can be any built-in or custom role, with optional per-project role overrides and environment limits. Managing Secret Keys on behalf of an organization takes the API Keys permissions. These can be created by going to `Settings -> API Keys`, where Admins can also require new Secret Keys to expire within a maximum lifetime. If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank (when using curl, add `:` at the end of the secret to indicate an empty password)


    ```bash

    curl https://api.growthbook.io/api/v1/features \

    -u secret_abc123DEF456:

    ```


    If using Bearer auth, pass the Secret Key as the token:


    ```bash

    curl https://api.growthbook.io/api/v1/features \

    -H "Authorization: Bearer secret_abc123DEF456"

    ```


    If a key has an expiration date, every response includes it in the `X-GrowthBook-Key-Expires-At` header (ISO 8601), so scripts can warn before the key stops working. Requests made with an expired key fail with a `401` that says where to create a replacement. See Expiration for choosing a key''s expiration, the warnings before it lapses, and the organization policies. ## Naming who asked


    Requests made with a Secret Key may add an `X-GrowthBook-Requested-By` header naming the organization member who asked for the change, as a user id or an email address. History, revision logs and webhooks show that member next to the key. Each key''s settings under `Settings -> API Keys`:


    - **Header**: **Optional** (the default) uses the header when it''s sent, **Required** rejects requests without it, and **Rejected** rejects requests that send it, each with a 400. - **Permissions**, when a member is named:

    - **Assume member''s role** (the default): the request acts as that member, with only what both the key and the member can do, so the header can narrow a key but never widen it. Drafts, owners, `mine` filters and reviews are the member''s. The member''s rights over their own drafts, comments and verdicts apply only where the key''s own role allows the same action. - **Use key''s role**: the key acts as itself, with its own permissions, and the name is only recorded in history. Drafts, verdicts and ownership are the key''s, as when no member is named.'
servers:
- url: https://api.growthbook.io/api
  description: GrowthBook Cloud
- url: https://{domain}/api
  description: Self-hosted GrowthBook
  variables:
    domain:
      default: localhost:3100
      description: Your self-hosted GrowthBook host (and port)
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Dimensions
  x-displayName: Dimensions
  description: Dimensions used during experiment analysis
paths:
  /v1/dimensions:
    get:
      operationId: listDimensions
      summary: Get all dimensions
      tags:
      - Dimensions
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/datasourceId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    dimensions:
                      type: array
                      items:
                        $ref: '#/components/schemas/Dimension'
                  required:
                  - dimensions
                  additionalProperties: false
                - $ref: '#/components/schemas/PaginationFields'
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET 'https://api.growthbook.io/api/v1/dimensions' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
    post:
      operationId: postDimension
      summary: Create a single dimension
      tags:
      - Dimensions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Short display name. Put details in `description`.
                  type: string
                description:
                  description: Description of the dimension
                  type: string
                  maxLength: 10000
                owner:
                  description: The userId or email address of the owner. If an email address is provided, it will be used to look up the userId of the matching organization member. If an ID is provided, it will be validated as existing in the organization.
                  type: string
                datasourceId:
                  description: ID of the datasource this dimension belongs to
                  type: string
                identifierType:
                  description: Type of identifier (user, anonymous, etc.)
                  type: string
                query:
                  description: SQL query or equivalent for the dimension
                  type: string
                managedBy:
                  description: Where this dimension must be managed from. If not set (empty string), it can be managed from anywhere.
                  type: string
                  enum:
                  - ''
                  - api
              required:
              - name
              - datasourceId
              - identifierType
              - query
              additionalProperties: false
      responses:
        '200':
          description: Resource created
          content:
            application/json:
              schema:
                type: object
                properties:
                  dimension:
                    $ref: '#/components/schemas/Dimension'
                required:
                - dimension
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST 'https://api.growthbook.io/api/v1/dimensions' \\\n  -H 'Authorization: Bearer YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\":\"User Country\",\"datasourceId\":\"ds_123abc\",\"identifierType\":\"user\",\"query\":\"SELECT country FROM users\"}'"
  /v1/dimensions/{id}:
    get:
      operationId: getDimension
      summary: Get a single dimension
      tags:
      - Dimensions
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  dimension:
                    $ref: '#/components/schemas/Dimension'
                required:
                - dimension
                additionalProperties: false
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET 'https://api.growthbook.io/api/v1/dimensions/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
    post:
      operationId: updateDimension
      summary: Update a single dimension
      tags:
      - Dimensions
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Short display name. Put details in `description`.
                  type: string
                description:
                  description: Description of the dimension
                  type: string
                  maxLength: 10000
                owner:
                  description: The userId or email address of the owner. If an email address is provided, it will be used to look up the userId of the matching organization member. If an ID is provided, it will be validated as existing in the organization.
                  type: string
                datasourceId:
                  description: ID of the datasource this dimension belongs to
                  type: string
                identifierType:
                  description: Type of identifier (user, anonymous, etc.)
                  type: string
                query:
                  description: SQL query or equivalent for the dimension
                  type: string
                managedBy:
                  description: Where this dimension must be managed from. If not set (empty string), it can be managed from anywhere.
                  type: string
                  enum:
                  - ''
                  - api
              additionalProperties: false
      responses:
        '200':
          description: Resource created
          content:
            application/json:
              schema:
                type: object
                properties:
                  dimension:
                    $ref: '#/components/schemas/Dimension'
                required:
                - dimension
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST 'https://api.growthbook.io/api/v1/dimensions/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"name\":\"User Region\"}'"
    delete:
      operationId: deleteDimension
      summary: Deletes a single dimension
      tags:
      - Dimensions
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Resource deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deletedId:
                    description: The ID of the deleted dimension
                    example: dim_123abc
                    type: string
                required:
                - deletedId
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X DELETE 'https://api.growthbook.io/api/v1/dimensions/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
components:
  schemas:
    PaginationFields:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        count:
          type: integer
        total:
          type: integer
        hasMore:
          type: boolean
        nextOffset:
          anyOf:
          - type: integer
          - type: 'null'
      required:
      - limit
      - offset
      - count
      - total
      - hasMore
      - nextOffset
      additionalProperties: false
    Dimension:
      type: object
      properties:
        id:
          type: string
        dateCreated:
          type: string
        dateUpdated:
          type: string
        owner:
          description: The userId of the owner (or raw owner name/email for legacy records)
          type: string
        ownerEmail:
          description: The email address of the owner, when the owner can be resolved to a known user.
          type: string
        datasourceId:
          type: string
        identifierType:
          type: string
        name:
          type: string
        description:
          type: string
          maxLength: 10000
        query:
          type: string
        managedBy:
          description: Where this dimension must be managed from. If not set (empty string), it can be managed from anywhere.
          type: string
          enum:
          - ''
          - api
          - config
      required:
      - id
      - dateCreated
      - dateUpdated
      - owner
      - datasourceId
      - identifierType
      - name
      - query
      additionalProperties: false
    Confirmation:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - rejected
          - expired
        actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                enum:
                - feature.create
                - feature.draft
                - feature.review
                - feature.publish
                - feature.archive
                - feature.delete
                - feature.other
                - experiment.create
                - experiment.draft
                - experiment.start
                - experiment.stop
                - experiment.targeting
                - experiment.traffic
                - experiment.phases
                - experiment.visualEditor
                - experiment.other
                - savedGroup.create
                - savedGroup.draft
                - savedGroup.review
                - savedGroup.publish
                - savedGroup.archive
                - savedGroup.delete
                - savedGroup.other
                - constant.create
                - constant.draft
                - constant.review
                - constant.publish
                - constant.archive
                - constant.delete
                - constant.other
                - config.create
                - config.draft
                - config.review
                - config.publish
                - config.archive
                - config.delete
                - config.other
                - rampSchedule.create
                - rampSchedule.start
                - rampSchedule.pause
                - rampSchedule.progression
                - rampSchedule.approve
                - rampSchedule.edit
                - rampSchedule.delete
                - rampSchedule.other
                - settings.approvals
                - settings.other
                - access.members
                - access.teams
                - customHook.create
                - customHook.edit
                - customHook.delete
                - environment.create
                - environment.edit
                - environment.delete
                - project.create
                - project.edit
                - project.delete
                - attribute.create
                - attribute.edit
                - attribute.delete
                - customField.create
                - customField.edit
                - customField.delete
                - sdkConnection.create
                - sdkConnection.edit
                - sdkConnection.delete
                - metric.create
                - metric.edit
                - metric.delete
                - factTable.create
                - factTable.edit
                - factTable.delete
                - segment.create
                - segment.edit
                - segment.delete
                - dimension.create
                - dimension.edit
                - dimension.delete
                - override.ignoreWarnings
                - override.skipSchemaValidation
                - override.skipHooks
                - override.bypassApproval
                - override.restBypassesReviews
                - override.draftLimit
                - override.skipChecklist
                - override.bypassDuplicateKeyCheck
                - other.write
              environments:
                type: array
                items:
                  type: string
            required:
            - action
            - environments
            additionalProperties: false
        summary:
          type: string
        url:
          type: string
        expiresAt:
          type: string
        response:
          anyOf:
          - type: object
            properties:
              status:
                type: number
              body: {}
            required:
            - status
            - body
            additionalProperties: false
          - type: 'null'
        note:
          anyOf:
          - type: string
          - type: 'null'
      required:
      - id
      - status
      - actions
      - summary
      - url
      - expiresAt
      - response
      - note
      additionalProperties: false
    ConfirmationHeld:
      type: object
      properties:
        confirmation:
          $ref: '#/components/schemas/Confirmation'
        message:
          type: string
      required:
      - confirmation
      - message
      additionalProperties: false
      $defs:
        Confirmation:
          id: Confirmation
          type: object
          properties:
            id:
              type: string
            status:
              type: string
              enum:
              - pending
              - running
              - completed
              - rejected
              - expired
            actions:
              type: array
              items:
                type: object
                properties:
                  action:
                    type: string
                    enum:
                    - feature.create
                    - feature.draft
                    - feature.review
                    - feature.publish
                    - feature.archive
                    - feature.delete
                    - feature.other
                    - experiment.create
                    - experiment.draft
                    - experiment.start
                    - experiment.stop
                    - experiment.targeting
                    - experiment.traffic
                    - experiment.phases
                    - experiment.visualEditor
                    - experiment.other
                    - savedGroup.create
                    - savedGroup.draft
                    - savedGroup.review
                    - savedGroup.publish
                    - savedGroup.archive
                    - savedGroup.delete
                    - savedGroup.other
                    - constant.create
                    - constant.draft
                    - constant.review
                    - constant.publish
                    - constant.archive
                    - constant.delete
                    - constant.other
                    - config.create
                    - config.draft
                    - config.review
                    - config.publish
                    - config.archive
                    - config.delete
                    - config.other
                    - rampSchedule.create
                    - rampSchedule.start
                    - rampSchedule.pause
                    - rampSchedule.progression
                    - rampSchedule.approve
                    - rampSchedule.edit
                    - rampSchedule.delete
                    - rampSchedule.other
                    - settings.approvals
                    - settings.other
                    - access.members
                    - access.teams
                    - customHook.create
                    - customHook.edit
                    - customHook.delete
                    - environment.create
                    - environment.edit
                    - environment.delete
                    - project.create
                    - project.edit
                    - project.delete
                    - attribute.create
                    - attribute.edit
                    - attribute.delete
                    - customField.create
                    - customField.edit
                    - customField.delete
                    - sdkConnection.create
                    - sdkConnection.edit
                    - sdkConnection.delete
                    - metric.create
                    - metric.edit
                    - metric.delete
                    - factTable.create
                    - factTable.edit
                    - factTable.delete
                    - segment.create
                    - segment.edit
                    - segment.delete
                    - dimension.create
                    - dimension.edit
                    - dimension.delete
                    - override.ignoreWarnings
                    - override.skipSchemaValidation
                    - override.skipHooks
                    - override.bypassApproval
                    - override.restBypassesReviews
                    - override.draftLimit
                    - override.skipChecklist
                    - override.bypassDuplicateKeyCheck
                    - other.write
                  environments:
                    type: array
                    items:
                      type: string
                required:
                - action
                - environments
                additionalProperties: false
            summary:
              type: string
            url:
              type: string
            expiresAt:
              type: string
            response:
              anyOf:
              - type: object
                properties:
                  status:
                    type: number
                  body: {}
                required:
                - status
                - body
                additionalProperties: false
              - type: 'null'
            note:
              anyOf:
              - type: string
              - type: 'null'
          required:
          - id
          - status
          - actions
          - summary
          - url
          - expiresAt
          - response
          - note
          additionalProperties: false
  parameters:
    limit:
      name: limit
      in: query
      description: The number of items to return
      schema:
        default: 10
        description: The number of items to return
        type: integer
        minimum: 1
        maximum: 100
    offset:
      name: offset
      in: query
      description: How many items to skip (use in conjunction with limit for pagination)
      schema:
        default: 0
        description: How many items to skip (use in conjunction with limit for pagination)
        type: integer
        minimum: 0
    id:
      name: id
      in: path
      required: true
      description: The id of the requested resource
      schema:
        description: The id of the requested resource
        type: string
    datasourceId:
      name: datasourceId
      in: query
      description: Filter by Data Source
      schema:
        description: Filter by Data Source
        type: string
  responses:
    ConfirmationHeld:
      description: Held until a person confirms it in GrowthBook. Poll the Location until the confirmation completes.
      headers:
        Location:
          description: The confirmation to poll
          schema:
            type: string
        Retry-After:
          description: Seconds to wait before polling
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConfirmationHeld'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'If using Bearer auth, pass the Secret Key as the token:

        ```bash

        curl https://api.growthbook.io/api/v1/features   -H "Authorization: Bearer secret_abc123DEF456"

        ```

        '
    basicAuth:
      type: http
      scheme: basic
      description: 'If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank:

        ```bash

        curl https://api.growthbook.io/api/v1/features   -u secret_abc123DEF456:

        # The ":" at the end stops curl from asking for a password

        ```

        '
x-tagGroups:
- name: Endpoints
  tags:
  - projects
  - environments
  - features-v2
  - feature-revisions-v2
  - features
  - feature-revisions
  - ramp-schedules
  - data-sources
  - fact-tables
  - fact-metrics
  - metrics
  - experiments
  - namespaces
  - snapshots
  - dimensions
  - segments
  - reports
  - sdk-connections
  - visual-changesets
  - saved-groups
  - saved-group-revisions
  - constants
  - constant-revisions
  - configs
  - config-revisions
  - releases
  - custom-hooks
  - organizations
  - members
  - code-references
  - archetypes
  - queries
  - settings
  - attributes
  - usage
  - meta
  - ContextualBandits
  - Dashboards
  - ContextualBanditQueries
  - CustomFields
  - MetricGroups
  - Teams
  - ExperimentTemplates
  - AnalyticsExplorations
  - RampScheduleTemplates
  - Learnings
  - Holdouts
  - AutoRuns
  - Populations
- name: Models
  tags:
  - AggregatedFactTable_model
  - AnalyticsExploration_model
  - Archetype_model
  - Attribute_model
  - AutoRun_model
  - CodeRef_model
  - Config_model
  - ConfigKeyUsage_model
  - ConfigLineage_model
  - ConfigReferences_model
  - ConfigRevision_model
  - ConfigRevisionActivityLogEntry_model
  - ConfigRevisionRef_model
  - ConfigRevisionReview_model
  - ConfigSchemaExport_model
  - ConfigSchemaSource_model
  - ConfigSchemaVerify_model
  - ConfigSchemaWarning_model
  - Confirmation_model
  - ConfirmationHeld_model
  - Constant_model
  - ConstantReferences_model
  - ConstantRevision_model
  - ConstantRevisionActivityLogEntry_model
  - ConstantRevisionRef_model
  - ConstantRevisionReview_model
  - ContextualBandit_model
  - ContextualBanditQuery_model
  - CustomField_model
  - CustomHook_model
  - Dashboard_model
  - DataSource_model
  - Dimension_model
  - Environment_model
  - EventUser_model
  - Experiment_model
  - Experiment Rule_model
  - ExperimentAnalysisSettings_model
  - ExperimentDecisionFrameworkSettings_model
  - ExperimentMetric_model
  - ExperimentMetricOverrideEntry_model
  - ExperimentResults_model
  - ExperimentSnapshot_model
  - ExperimentTemplate_model
  - ExperimentWithEnhancedStatus_model
  - FactMetric_model
  - FactTable_model
  - FactTableColumn_model
  - FactTableFilter_model
  - FeatureBaseRule_model
  - FeatureContextualBanditRefRule_model
  - FeatureDefinition_model
  - FeatureEnvironmentV1_model
  - FeatureEnvironmentV2_model
  - FeatureExperimentRefRule_model
  - FeatureExperimentRule_model
  - FeatureForceRule_model
  - FeatureRevisionRef_model
  - FeatureRevisionSummary_model
  - FeatureRevisionV1_model
  - FeatureRevisionV2_model
  - FeatureRolloutRule_model
  - FeatureRuleV1_model
  - FeatureRuleV2_model
  - FeatureSafeRolloutRule_model
  - FeatureV1_model
  - FeatureV2_model
  - FeatureWithRevisionsV1_model
  - FeatureWithRevisionsV2_model
  - Holdout_model
  - InformationSchema_model
  - InformationSchemaTable_model
  - Learning_model
  - LookbackOverride_model
  - Member_model
  - Metric_model
  - MetricAnalysis_model
  - MetricGroup_model
  - MetricUsage_model
  - Namespace_model
  - NamespaceExperimentMember_model
  - Organization_model
  - PaginationFields_model
  - Population_model
  - Project_model
  - Query_model
  - RampSchedule_model
  - RampScheduleTemplate_model
  - Report_model
  - RequireReviewRule_model
  - RequireReviewRuleInput_model
  - RevisionIdRef_model
  - Safe Rollout Rule_model
  - SavedGroup_model
  - SavedGroupApprovalRule_model
  - SavedGroupReferenceResource_model
  - SavedGroupReferences_model
  - SavedGroupRevision_model
  - SavedGroupRevisionActivityLogEntry_model
  - SavedGroupRevisionRef_model
  - SavedGroupRevisionReview_model
  - ScheduleRule_model
  - ScheduledStopPlan_model
  - SdkConnection_model
  - Segment_model
  - Settings_model
  - Targeting Rule_model
  - TargetingReviewRule_model
  - Team_model
  - VisualChange_model
  - VisualChangeset_model
  - VisualEditorCbExperimentStub_model
x-provenance:
  method: harvested
  publisher: GrowthBook
  source: https://docs.growthbook.io/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)