# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitLab Admin API
  version: 1.0.0
extends: openapi/gitlab-admin-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/api/v4/admin/batched_background_migrations/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a batched background migration
      effect: read
      questions:
      - How do I check the progress of one batched background migration on my instance?
      - Can I look up a background migration in a specific database, like ci?
      instructions:
      - text: Show batched background migration {id}.
        slots:
          id: path.id
      - text: Get background migration {id} from the {database} database.
        slots:
          id: path.id
          database: query.database
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/batched_background_migrations'].get
  update:
    x-apievangelist-phrasing:
      intent: List batched background migrations
      effect: read
      questions:
      - Which batched background migrations are running or queued on my self-managed GitLab?
      - Can I list background migrations for just one database?
      instructions:
      - text: List all batched background migrations.
      - text: List the batched background migrations in the {database} database.
        slots:
          database: query.database
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/batched_background_migrations/{id}/resume'].put
  update:
    x-apievangelist-phrasing:
      intent: Resume a paused background migration
      effect: write
      questions:
      - How do I restart a batched background migration I paused?
      - Can I resume a paused migration after maintenance is over?
      instructions:
      - text: Resume batched background migration {id}.
        slots:
          id: path.id
      - text: Resume paused migration {id} on the {database} database.
        slots:
          id: path.id
          database: requestBody.database
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/batched_background_migrations/{id}/pause'].put
  update:
    x-apievangelist-phrasing:
      intent: Pause a batched background migration
      effect: write
      questions:
      - How do I temporarily halt a batched background migration that is loading the database?
      - Can I pause a running migration and pick it up later?
      instructions:
      - text: Pause batched background migration {id}.
        slots:
          id: path.id
      - text: Pause the running migration {id} on the {database} database.
        slots:
          id: path.id
          database: requestBody.database
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/ci/variables/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an instance-level CI variable
      effect: read
      questions:
      - How do I read the value and settings of one instance-wide CI/CD variable?
      - Is a given instance-level variable masked or protected?
      instructions:
      - text: Show instance CI variable {key}.
        slots:
          key: path.key
      - text: Get the value and flags of instance-level variable {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/ci/variables/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an instance-level CI variable
      effect: write
      questions:
      - How do I change the value of an existing instance-wide CI variable?
      - Can I mark an existing instance variable as masked or protected?
      instructions:
      - text: Set instance CI variable {key} to {value}.
        slots:
          key: path.key
          value: requestBody.value
      - text: 'Make existing instance variable {key} masked: {masked}.'
        slots:
          key: path.key
          masked: requestBody.masked
      - text: Change instance variable {key} to protected={protected}.
        slots:
          key: path.key
          protected: requestBody.protected
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/ci/variables/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an instance-level CI variable
      effect: destructive
      questions:
      - How do I remove a CI/CD variable that applies to every project on the instance?
      - Can I delete an instance-level variable by its key?
      instructions:
      - text: Delete instance CI variable {key}.
        slots:
          key: path.key
      - text: Remove the instance-wide variable {key}.
        slots:
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/ci/variables'].get
  update:
    x-apievangelist-phrasing:
      intent: List instance-level CI variables
      effect: read
      questions:
      - What CI/CD variables are defined at the instance level?
      - Where can an admin see every instance-wide pipeline variable?
      instructions:
      - text: List all instance-level CI variables.
      - text: Show page {page} of the instance CI variables.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/ci/variables'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an instance-level CI variable
      effect: write
      questions:
      - How do I add a CI/CD variable that every project on my GitLab instance can use?
      - Can I create an instance variable as a file type instead of an env var?
      instructions:
      - text: Create instance CI variable {key} with value {value}.
        slots:
          key: requestBody.key
          value: requestBody.value
      - text: Add a masked instance-wide variable {key} set to {value}, masked {masked}.
        slots:
          key: requestBody.key
          value: requestBody.value
          masked: requestBody.masked
      - text: Create instance variable {key} = {value} of type {variable_type}.
        slots:
          key: requestBody.key
          value: requestBody.value
          variable_type: requestBody.variable_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/databases/{database_name}/dictionary/tables/{table_name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a database table's dictionary entry
      effect: read
      questions:
      - How do I find which feature and owning team a GitLab database table belongs to?
      - Can I read the database dictionary details for one table?
      instructions:
      - text: Show the dictionary entry for table {table_name} in database {database_name}.
        slots:
          table_name: path.table_name
          database_name: path.database_name
      - text: Look up table {table_name} in the {database_name} database dictionary.
        slots:
          table_name: path.table_name
          database_name: path.database_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/clusters/{cluster_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an instance Kubernetes cluster
      effect: read
      questions:
      - How do I view the configuration of one instance-level Kubernetes cluster?
      - What environment scope and domain does a given instance cluster have?
      instructions:
      - text: Show instance cluster {cluster_id}.
        slots:
          cluster_id: path.cluster_id
      - text: Get the settings of instance Kubernetes cluster {cluster_id}.
        slots:
          cluster_id: path.cluster_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/clusters/{cluster_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit an instance Kubernetes cluster
      effect: write
      questions:
      - How do I change the API URL or token of an instance cluster already connected?
      - Can I disable an instance cluster or change its environment scope?
      instructions:
      - text: Rename instance cluster {cluster_id} to {name}.
        slots:
          cluster_id: path.cluster_id
          name: requestBody.name
      - text: Set the environment scope of instance cluster {cluster_id} to {environment_scope}.
        slots:
          cluster_id: path.cluster_id
          environment_scope: requestBody.environment_scope
      - text: Update instance cluster {cluster_id} to use Kubernetes API URL {api_url}.
        slots:
          cluster_id: path.cluster_id
          api_url: requestBody.platform_kubernetes_attributes[api_url]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/clusters/{cluster_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an instance Kubernetes cluster
      effect: destructive
      questions:
      - How do I disconnect an instance-level Kubernetes cluster from GitLab?
      - Does deleting an instance cluster remove the resources running inside it?
      instructions:
      - text: Delete instance cluster {cluster_id}.
        slots:
          cluster_id: path.cluster_id
      - text: Disconnect instance Kubernetes cluster {cluster_id} from GitLab.
        slots:
          cluster_id: path.cluster_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/clusters/add'].post
  update:
    x-apievangelist-phrasing:
      intent: Connect an existing Kubernetes cluster to the instance
      effect: write
      questions:
      - How do I connect an existing Kubernetes cluster at the instance level?
      - What credentials are required to add an instance cluster?
      instructions:
      - text: Add instance cluster {name} with API URL {api_url} and token {token}.
        slots:
          name: requestBody.name
          api_url: requestBody.platform_kubernetes_attributes[api_url]
          token: requestBody.platform_kubernetes_attributes[token]
      - text: Connect Kubernetes cluster {name} at {api_url} using token {token} for scope {environment_scope}.
        slots:
          name: requestBody.name
          api_url: requestBody.platform_kubernetes_attributes[api_url]
          token: requestBody.platform_kubernetes_attributes[token]
          environment_scope: requestBody.environment_scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/clusters'].get
  update:
    x-apievangelist-phrasing:
      intent: List instance Kubernetes clusters
      effect: read
      questions:
      - Which Kubernetes clusters are connected at the instance level?
      - Where can an admin see all instance-wide clusters?
      instructions:
      - text: List all instance clusters.
      - text: Show every Kubernetes cluster attached to the instance.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/admin/migrations/{timestamp}/mark'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a database migration as executed
      effect: write
      questions:
      - How do I mark a failed database migration as successfully run so upgrades can continue?
      - Can I flag a migration as done on a specific database only?
      instructions:
      - text: Mark migration {timestamp} as successfully executed.
        slots:
          timestamp: path.timestamp
      - text: Mark migration {timestamp} as done on the {database} database.
        slots:
          timestamp: path.timestamp
          database: requestBody.database
      method: generated
      generated: '2026-09-26'