GitLab Experiments API

openapi: 3.2.0
info:
  title: GitLab REST Experiments API
  description: GitLab REST API used to interact with a GitLab installation.
  termsOfService: https://handbook.gitlab.com/handbook/legal/api-terms/
  version: '19.6'
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
    x-gitlab-description: The license applies to the OpenAPI specification document itself. For terms governing use of the GitLab API, see the termsOfService field.
servers:
- url: https://{hostname}
  description: GitLab REST API
  variables:
    hostname:
      default: gitlab.com
      description: Your GitLab instance hostname
security:
- http: []
- oauth2: []
- apiKey: []
tags:
- name: Experiments
  description: 'Use this API to retrieve the A/B experiments running on an instance. This API is for internal use

    only, requires you to be a GitLab team member,

    and cannot be used with anonymous or unauthenticated users. For experiments involving anonymous users,

    use the `glex_force` query parameter

    instead.'
  x-displayName: Experiments
  externalDocs:
    url: https://docs.gitlab.com/api/experiments/
paths:
  /api/v4/experiments:
    get:
      operationId: getApiV4Experiments
      summary: List all experiments
      description: Lists all experiments on the GitLab instance. Each experiment has an `enabled` status that indicates whether the experiment is enabled globally, or only in specific contexts.
      tags:
      - Experiments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEntitiesExperiment'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /api/v4/experiments/{name}/cache:
    delete:
      operationId: deleteApiV4ExperimentsNameCache
      summary: Delete cached assignments for an experiment
      description: Removes all cached variant assignments for the experiment with the given cache key. Useful for cleaning up completed experiments whose code has been removed from the codebase.
      tags:
      - Experiments
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: name
        required: true
        description: Cache key of the experiment to clear.
        schema:
          type: string
        in: path
  /api/v4/experiments/{experiment_name}/assignments:
    get:
      operationId: getApiV4ExperimentsExperimentNameAssignments
      summary: Get current variant assignment for an experiment context
      description: Returns the currently cached variant assignment for the given experiment and context. Defaults to current user if no context is provided.
      tags:
      - Experiments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesExperimentsAssignment'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: experiment_name
        required: true
        description: The experiment name
        schema:
          type: string
        in: path
      - name: context
        required: false
        description: Context parameters (user, namespace, project). Pass every key the experiment declares in `context_keys`. Experiments can declare multiple keys. An actor context is resolved from the user. The user defaults to the current user.
        schema:
          type:
          - object
          - 'null'
        in: query
    post:
      operationId: postApiV4ExperimentsExperimentNameAssignments
      summary: Force a variant assignment for an experiment context
      description: Forces a specific variant assignment for the given experiment and context. The assignment is stored in Redis cache and will persist until overwritten. Defaults to current user if no context is provided.
      tags:
      - Experiments
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEntitiesExperimentsAssignment'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: experiment_name
        required: true
        description: The experiment name
        schema:
          type: string
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postApiV4ExperimentsExperimentNameAssignmentsRequest'
    delete:
      operationId: deleteApiV4ExperimentsExperimentNameAssignments
      summary: Clear a variant assignment for an experiment context
      description: Removes the cached variant assignment for the given experiment and context, returning the actor to normal rollout assignment. Defaults to current user if no context is provided.
      tags:
      - Experiments
      responses:
        '204':
          description: No Content
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      parameters:
      - name: experiment_name
        required: true
        description: The experiment name
        schema:
          type: string
        in: path
      - name: context
        required: false
        description: Context parameters (user, namespace, project). An actor context is resolved from the user. Defaults to current user.
        schema:
          type:
          - object
          - 'null'
        in: query
components:
  schemas:
    postApiV4ExperimentsExperimentNameAssignmentsRequest:
      type: object
      properties:
        variant:
          type:
          - string
          - 'null'
          description: Variant name to assign, for example `control` or `candidate`.
        context:
          type:
          - object
          - 'null'
          description: Context parameters (user, namespace, project). An actor context is resolved from the user. Defaults to current user.
      required:
      - variant
    APIEntitiesExperimentsAssignment:
      type: object
      properties:
        experiment:
          type: string
          example: lightweight_trial_registration_redesign
        variant:
          type: string
          example: candidate
        context_key:
          type: string
          example: abc123def456
        cached:
          type: boolean
          example: true
    APIEntitiesExperimentCurrentStatus:
      type: object
      properties:
        state:
          type: string
          example: 'on'
        gates:
          $ref: '#/components/schemas/APIEntitiesFeatureGate'
    APIEntitiesFeatureDefinition:
      type: object
      properties:
        name:
          type: string
        feature_issue_url:
          type: string
        introduced_by_url:
          type: string
        rollout_issue_url:
          type: string
        milestone:
          type: string
        log_state_changes:
          type: boolean
        type:
          type: string
        group:
          type: string
        default_enabled:
          type: boolean
        intended_to_rollout_by:
          type: string
    APIEntitiesExperiment:
      type: object
      properties:
        key:
          type: string
          example: code_quality_walkthrough
        context:
          type: array
          example:
          - user
          items:
            type: string
        definition:
          $ref: '#/components/schemas/APIEntitiesFeatureDefinition'
        current_status:
          $ref: '#/components/schemas/APIEntitiesExperimentCurrentStatus'
    APIEntitiesFeatureGate:
      type: object
      properties:
        key:
          type: string
          example: percentage_of_actors
        value:
          type: integer
          example: 34
  securitySchemes:
    http:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://gitlab.com/oauth/authorize
          tokenUrl: https://gitlab.com/oauth/token
          refreshUrl: https://gitlab.com/oauth/token
          scopes:
            api: Grants complete read/write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry.
            read_api: Grants read access to the API, including all groups and projects, the container registry, and the package registry.
            read_user: Grants read-only access to your profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
            create_runner: Grants create access to the runners.
            manage_runner: Grants access to manage the runners.
            k8s_proxy: Grants permission to perform Kubernetes API calls using the agent for Kubernetes.
            self_rotate: Grants permission for token to rotate itself.
            mcp: Grants read-write access to remote Model Context Protocol (MCP) server for tools execution.
            mcp_orbit: Grants access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval.
    apiKey:
      type: apiKey
      name: PRIVATE-TOKEN
      in: header