GrowthBook Attributes API

openapi: 3.2.0
info:
  version: 5.1.0
  title: GrowthBook REST Attributes 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: Attributes
  x-displayName: Attributes
  description: Used when targeting feature flags and experiments.
paths:
  /v1/attributes:
    get:
      operationId: listAttributes
      summary: Get the organization's attributes
      tags:
      - Attributes
      parameters:
      - name: projectId
        in: query
        description: Filter to attributes available in this project — includes org-wide attributes (no project restriction) and attributes explicitly scoped to this project.
        schema:
          description: Filter to attributes available in this project — includes org-wide attributes (no project restriction) and attributes explicitly scoped to this project.
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  attributes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Attribute'
                required:
                - attributes
                additionalProperties: false
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET 'https://api.growthbook.io/api/v1/attributes' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
    post:
      operationId: postAttribute
      summary: Create a new attribute
      tags:
      - Attributes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                property:
                  description: Attribute name exactly as your SDK passes it (e.g. `userId`). The API can't rename it, and renaming it in the UI doesn't update SDK code or targeting conditions.
                  type: string
                datatype:
                  description: The attribute datatype
                  type: string
                  enum:
                  - boolean
                  - string
                  - number
                  - secureString
                  - enum
                  - string[]
                  - number[]
                  - secureString[]
                description:
                  description: Markdown. Put context here, not in the name.
                  type: string
                archived:
                  description: The attribute is archived
                  type: boolean
                hashAttribute:
                  description: Shall the attribute be hashed
                  type: boolean
                enum:
                  description: Comma-separated list of allowed values. Required for the 'enum' datatype. For array datatypes (string[], number[], secureString[]) it optionally restricts the list to these values. Ignored for all other datatypes.
                  type: string
                format:
                  description: The attribute's format
                  type: string
                  enum:
                  - ''
                  - version
                  - date
                  - isoCountryCode
                projects:
                  description: Project IDs that can use this. An empty list means all Projects. Projects control access and availability, so don't use them as labels.
                  type: array
                  items:
                    type: string
                tags:
                  description: Tags for filtering and grouping. Use these instead of encoding groups in names.
                  type: array
                  items:
                    type: string
                customFields:
                  description: Values for the organization's attribute custom fields, keyed by field id
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: string
              required:
              - property
              - datatype
              additionalProperties: false
      responses:
        '200':
          description: Resource created
          content:
            application/json:
              schema:
                type: object
                properties:
                  attribute:
                    $ref: '#/components/schemas/Attribute'
                required:
                - attribute
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST 'https://api.growthbook.io/api/v1/attributes' \\\n  -H 'Authorization: Bearer YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"property\":\"foo\",\"datatype\":\"boolean\",\"description\":\"My new attribute\"}'"
  /v1/attributes/{property}:
    put:
      operationId: putAttribute
      summary: Update an attribute
      tags:
      - Attributes
      parameters:
      - $ref: '#/components/parameters/property'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                datatype:
                  description: The attribute datatype
                  type: string
                  enum:
                  - boolean
                  - string
                  - number
                  - secureString
                  - enum
                  - string[]
                  - number[]
                  - secureString[]
                description:
                  description: Markdown. Put context here, not in the name.
                  type: string
                archived:
                  description: The attribute is archived
                  type: boolean
                hashAttribute:
                  description: Shall the attribute be hashed
                  type: boolean
                enum:
                  description: Comma-separated list of allowed values. Required for the 'enum' datatype. For array datatypes (string[], number[], secureString[]) it optionally restricts the list to these values. Ignored for all other datatypes.
                  type: string
                format:
                  description: The attribute's format
                  type: string
                  enum:
                  - ''
                  - version
                  - date
                  - isoCountryCode
                projects:
                  description: Project IDs that can use this. An empty list means all Projects. Projects control access and availability, so don't use them as labels.
                  type: array
                  items:
                    type: string
                tags:
                  description: Tags for filtering and grouping. Use these instead of encoding groups in names.
                  type: array
                  items:
                    type: string
                customFields:
                  description: Values for the organization's attribute custom fields, keyed by field id
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    type: string
              additionalProperties: false
      responses:
        '200':
          description: Resource updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  attribute:
                    $ref: '#/components/schemas/Attribute'
                required:
                - attribute
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X PUT 'https://api.growthbook.io/api/v1/attributes/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"description\":\"My updated attribute\"}'"
    delete:
      operationId: deleteAttribute
      summary: Deletes a single attribute
      tags:
      - Attributes
      parameters:
      - $ref: '#/components/parameters/property'
      responses:
        '200':
          description: Resource deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deletedProperty:
                    type: string
                required:
                - deletedProperty
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X DELETE 'https://api.growthbook.io/api/v1/attributes/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
components:
  parameters:
    property:
      name: property
      in: path
      required: true
      description: The attribute property
      schema:
        description: The attribute property
        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'
  schemas:
    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
    Attribute:
      type: object
      properties:
        property:
          type: string
        datatype:
          type: string
          enum:
          - boolean
          - string
          - number
          - secureString
          - enum
          - string[]
          - number[]
          - secureString[]
        description:
          type: string
        hashAttribute:
          type: boolean
        archived:
          type: boolean
        enum:
          description: Comma-separated list of allowed values. Required for the 'enum' datatype. For array datatypes (string[], number[], secureString[]) it optionally restricts the list to these values. Ignored for all other datatypes.
          type: string
        format:
          type: string
          enum:
          - ''
          - version
          - date
          - isoCountryCode
        projects:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        customFields:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
      required:
      - property
      - datatype
      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
  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)