GrowthBook Archetypes API

openapi: 3.2.0
info:
  version: 5.1.0
  title: GrowthBook REST Archetypes 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: Archetypes
  x-displayName: Archetypes
  description: Archetypes allow you to simulate the result of targeting rules on pre-set user attributes
paths:
  /v1/archetypes:
    get:
      operationId: listArchetypes
      summary: Get the organization's archetypes
      tags:
      - Archetypes
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  archetypes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Archetype'
                required:
                - archetypes
                additionalProperties: false
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET 'https://api.growthbook.io/api/v1/archetypes' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
    post:
      operationId: postArchetype
      summary: Create a single archetype
      tags:
      - Archetypes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Short display name (e.g. `Logged-out US visitor`).
                  type: string
                description:
                  description: Put context here, not in the name.
                  type: string
                  maxLength: 10000
                isPublic:
                  description: Whether to make this Archetype available to other team members
                  type: boolean
                attributes:
                  description: The attributes to set when using this Archetype
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                projects:
                  type: array
                  items:
                    type: string
                environments:
                  description: Limit this Archetype to specific environments. Omit or leave empty to apply to all environments.
                  type: array
                  items:
                    type: string
              required:
              - name
              - isPublic
              additionalProperties: false
      responses:
        '200':
          description: Resource created
          content:
            application/json:
              schema:
                type: object
                properties:
                  archetype:
                    $ref: '#/components/schemas/Archetype'
                required:
                - archetype
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X POST 'https://api.growthbook.io/api/v1/archetypes' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
  /v1/archetypes/{id}:
    get:
      operationId: getArchetype
      summary: Get a single archetype
      tags:
      - Archetypes
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  archetype:
                    $ref: '#/components/schemas/Archetype'
                required:
                - archetype
                additionalProperties: false
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET 'https://api.growthbook.io/api/v1/archetypes/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
    put:
      operationId: putArchetype
      summary: Update a single archetype
      tags:
      - Archetypes
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Short display name (e.g. `Logged-out US visitor`).
                  type: string
                description:
                  description: Put context here, not in the name.
                  type: string
                  maxLength: 10000
                isPublic:
                  description: Whether to make this Archetype available to other team members
                  type: boolean
                attributes:
                  description: The attributes to set when using this Archetype
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                projects:
                  type: array
                  items:
                    type: string
                environments:
                  description: Limit this Archetype to specific environments. Omit or leave empty to apply to all environments.
                  type: array
                  items:
                    type: string
              additionalProperties: false
      responses:
        '200':
          description: Resource updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  archetype:
                    $ref: '#/components/schemas/Archetype'
                required:
                - archetype
                additionalProperties: false
        '202':
          $ref: '#/components/responses/ConfirmationHeld'
      x-codeSamples:
      - lang: cURL
        source: "curl -X PUT 'https://api.growthbook.io/api/v1/archetypes/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"description\":\"New description\"}'"
    delete:
      operationId: deleteArchetype
      summary: Deletes a single archetype
      tags:
      - Archetypes
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Resource deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deletedId:
                    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/archetypes/abc123' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
components:
  schemas:
    Archetype:
      type: object
      properties:
        id:
          type: string
        dateCreated:
          type: string
        dateUpdated:
          type: string
        name:
          type: string
        description:
          type: string
          maxLength: 10000
        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
        isPublic:
          type: boolean
        attributes:
          description: The attributes to set when using this Archetype
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        projects:
          type: array
          items:
            type: string
        environments:
          description: Limit this Archetype to specific environments. Omit or leave empty to apply to all environments.
          type: array
          items:
            type: string
      required:
      - id
      - dateCreated
      - dateUpdated
      - name
      - owner
      - isPublic
      - attributes
      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
  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'
  parameters:
    id:
      name: id
      in: path
      required: true
      description: The id of the requested resource
      schema:
        description: The id of the requested resource
        type: string
  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)