# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitLab Projects API
  version: 1.0.0
extends: openapi/gitlab-projects-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: 26
- target: $.paths['/api/v4/projects/{id}/repository/merged_branches'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all merged branches in a project
      effect: destructive
      questions:
      - How do I clean up every branch that has already been merged in a GitLab project?
      - Can I bulk-remove merged branches from a repository in one call?
      instructions:
      - text: Delete all merged branches in project {id}.
        slots:
          id: path.id
      - text: Clean up the already-merged branches from the {id} repository.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/repository/branches/{branch}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a single branch
      effect: read
      questions:
      - Where can I see the details and latest commit of one specific branch?
      - What does a single repository branch record look like for a project?
      instructions:
      - text: Show me the details of branch {branch} in project {id}.
        slots:
          branch: path.branch
          id: path.id
      - text: Fetch the {branch} branch record from project {id}.
        slots:
          branch: path.branch
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/repository/branches/{branch}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single branch
      effect: destructive
      questions:
      - How do I delete one named branch from a project repository?
      - Can I remove a specific feature branch I no longer need?
      instructions:
      - text: Delete branch {branch} from project {id}.
        slots:
          branch: path.branch
          id: path.id
      - text: Remove the {branch} branch in repository {id}.
        slots:
          branch: path.branch
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/repository/branches/{branch}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check whether a branch exists
      effect: read
      questions:
      - Is there a quick way to check if a branch exists without fetching its details?
      - Can I verify a branch name is present in a repository before pushing to it?
      instructions:
      - text: Check whether branch {branch} exists in project {id}.
        slots:
          branch: path.branch
          id: path.id
      - text: Confirm that project {id} has a branch called {branch}.
        slots:
          branch: path.branch
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/repository/branches'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's repository branches
      effect: read
      questions:
      - How do I list all the branches in a GitLab project repository?
      - Can I search branches by name or with a regex pattern?
      - Which sort orders are available when listing repository branches?
      instructions:
      - text: List the branches in project {id}.
        slots:
          id: path.id
      - text: Find branches in project {id} whose names match {search}.
        slots:
          id: path.id
          search: query.search
      - text: List branches in project {id} matching the regex {regex}.
        slots:
          id: path.id
          regex: query.regex
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/repository/branches'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new branch from a ref
      effect: write
      questions:
      - How do I create a new branch from main or a specific commit?
      - Can I branch off a tag or commit SHA instead of another branch?
      instructions:
      - text: Create branch {branch} from {ref} in project {id}.
        slots:
          branch: query.branch
          ref: query.ref
          id: path.id
      - text: Start a new branch {branch} in repository {id} off commit {ref}.
        slots:
          branch: query.branch
          id: path.id
          ref: query.ref
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/repository/branches/{branch}/unprotect'].put
  update:
    x-apievangelist-phrasing:
      intent: Remove protection from a branch
      effect: write
      questions:
      - How do I unprotect a branch so anyone with access can push to it?
      - Can I lift branch protection from a single branch?
      instructions:
      - text: Unprotect branch {branch} in project {id}.
        slots:
          branch: path.branch
          id: path.id
      - text: Remove the protection rules from {branch} in repository {id}.
        slots:
          branch: path.branch
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/repository/branches/{branch}/protect'].put
  update:
    x-apievangelist-phrasing:
      intent: Protect a branch
      effect: write
      questions:
      - How do I protect a branch so it can't be force-pushed or deleted?
      - Can I protect a branch but still allow developers to push or merge into it?
      instructions:
      - text: Protect branch {branch} in project {id}.
        slots:
          branch: path.branch
          id: path.id
      - text: Protect {branch} in project {id} and set developers-can-merge to {developers_can_merge}.
        slots:
          branch: path.branch
          id: path.id
          developers_can_merge: requestBody.developers_can_merge
      - text: Protect {branch} in project {id} with developers allowed to push set to {developers_can_push}.
        slots:
          branch: path.branch
          id: path.id
          developers_can_push: requestBody.developers_can_push
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/badges/{badge_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a project badge
      effect: read
      questions:
      - How do I look up one badge on a project by its ID?
      - What link and image URL does a specific project badge use?
      instructions:
      - text: Show project badge {badge_id} on project {id}.
        slots:
          badge_id: path.badge_id
          id: path.id
      - text: Get the link and image URLs of badge {badge_id} in project {id}.
        slots:
          badge_id: path.badge_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/badges/{badge_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a project badge
      effect: write
      questions:
      - How do I change the image or link of an existing project badge?
      - Can I rename a badge that's already on my project?
      instructions:
      - text: Change the image URL of project badge {badge_id} on {id} to {image_url}.
        slots:
          badge_id: path.badge_id
          id: path.id
          image_url: requestBody.image_url
      - text: Point project badge {badge_id} in {id} at link {link_url}.
        slots:
          badge_id: path.badge_id
          id: path.id
          link_url: requestBody.link_url
      - text: Rename project badge {badge_id} on {id} to {name}.
        slots:
          badge_id: path.badge_id
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/badges/{badge_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a badge from a project
      effect: destructive
      questions:
      - How do I take a badge off my project's page?
      - Can I delete a single project badge without touching group badges?
      instructions:
      - text: Remove badge {badge_id} from project {id}.
        slots:
          badge_id: path.badge_id
          id: path.id
      - text: Delete the project badge {badge_id} on {id}.
        slots:
          badge_id: path.badge_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/badges'].get
  update:
    x-apievangelist-phrasing:
      intent: List a project's badges
      effect: read
      questions:
      - Which badges are shown on a project?
      - Can I filter a project's badges by name?
      instructions:
      - text: List all badges on project {id}.
        slots:
          id: path.id
      - text: Find badges named {name} on project {id}.
        slots:
          name: query.name
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/badges'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a badge to a project
      effect: write
      questions:
      - How do I add a pipeline status or coverage badge to a GitLab project?
      - What do I need to supply to create a new project badge?
      instructions:
      - text: Add a badge to project {id} linking to {link_url} with image {image_url}.
        slots:
          id: path.id
          link_url: requestBody.link_url
          image_url: requestBody.image_url
      - text: Create a project badge called {name} on {id} using image {image_url} and link {link_url}.
        slots:
          name: requestBody.name
          id: path.id
          image_url: requestBody.image_url
          link_url: requestBody.link_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/badges/render'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview how a project badge will render
      effect: read
      questions:
      - Can I preview a project badge's resolved URLs before adding it?
      - How do I check what placeholders in a badge URL resolve to for my project?
      instructions:
      - text: Preview a badge for project {id} with link {link_url} and image {image_url}.
        slots:
          id: path.id
          link_url: query.link_url
          image_url: query.image_url
      - text: Render the project badge URLs {image_url} and {link_url} for {id} without saving.
        slots:
          image_url: query.image_url
          link_url: query.link_url
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/access_requests/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Deny a user's request to join a project
      effect: destructive
      questions:
      - How do I reject someone who requested access to my project?
      - Can I deny a pending project access request for a specific user?
      instructions:
      - text: Deny user {user_id}'s access request on project {id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Reject the pending request from {user_id} to join project {id}.
        slots:
          user_id: path.user_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/access_requests/{user_id}/approve'].put
  update:
    x-apievangelist-phrasing:
      intent: Approve a user's request to join a project
      effect: write
      questions:
      - How do I approve someone who asked to join my project?
      - Can I choose the access level when approving a project access request?
      instructions:
      - text: Approve user {user_id}'s request to join project {id}.
        slots:
          user_id: path.user_id
          id: path.id
      - text: Let {user_id} into project {id} with access level {access_level}.
        slots:
          user_id: path.user_id
          id: path.id
          access_level: requestBody.access_level
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/access_requests'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending access requests for a project
      effect: read
      questions:
      - Who has requested access to my project and is still waiting?
      - Where can I see the pending membership requests on a project?
      instructions:
      - text: List the pending access requests for project {id}.
        slots:
          id: path.id
      - text: Show who is waiting to be let into project {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/access_requests'].post
  update:
    x-apievangelist-phrasing:
      intent: Request access to a project for yourself
      effect: write
      questions:
      - How do I ask to become a member of a project I can see but can't contribute to?
      - Can I submit an access request to a project on my own behalf?
      instructions:
      - text: Request access to project {id} for me.
        slots:
          id: path.id
      - text: Submit my request to join project {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images/{metric_image_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a metric image on an alert
      effect: write
      questions:
      - How do I change the link attached to a metric image on an alert?
      - Can I edit the link text of a chart I already uploaded to an alert?
      instructions:
      - text: Set the URL of metric image {metric_image_id} on alert {alert_iid} in project {id} to {url}.
        slots:
          metric_image_id: path.metric_image_id
          alert_iid: path.alert_iid
          id: path.id
          url: requestBody.url
      - text: Change the link text of metric image {metric_image_id} on alert {alert_iid} in {id} to {url_text}.
        slots:
          metric_image_id: path.metric_image_id
          alert_iid: path.alert_iid
          id: path.id
          url_text: requestBody.url_text
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images/{metric_image_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a metric image from an alert
      effect: destructive
      questions:
      - How do I delete a chart screenshot I attached to an alert by mistake?
      - Can I remove one metric image from an alert without affecting the others?
      instructions:
      - text: Remove metric image {metric_image_id} from alert {alert_iid} in project {id}.
        slots:
          metric_image_id: path.metric_image_id
          alert_iid: path.alert_iid
          id: path.id
      - text: Delete the metric image {metric_image_id} attached to alert {alert_iid} of {id}.
        slots:
          metric_image_id: path.metric_image_id
          alert_iid: path.alert_iid
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images'].get
  update:
    x-apievangelist-phrasing:
      intent: List metric images on an alert
      effect: read
      questions:
      - Which metric images have been attached to an incident alert?
      - Can I see all the charts uploaded to an alert in one list?
      instructions:
      - text: List the metric images on alert {alert_iid} in project {id}.
        slots:
          alert_iid: path.alert_iid
          id: path.id
      - text: Show every chart attached to alert {alert_iid} of project {id}.
        slots:
          alert_iid: path.alert_iid
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a metric image to an alert
      effect: write
      questions:
      - How do I attach a screenshot of a metrics chart to an alert?
      - Can I link an uploaded alert image back to the dashboard it came from?
      instructions:
      - text: Upload {file} as a metric image on alert {alert_iid} in project {id}.
        slots:
          file: requestBody.file
          alert_iid: path.alert_iid
          id: path.id
      - text: Attach image {file} to alert {alert_iid} of {id} with a link to {url}.
        slots:
          file: requestBody.file
          alert_iid: path.alert_iid
          id: path.id
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/alert_management_alerts/{alert_iid}/metric_images/authorize'].post
  update:
    x-apievangelist-phrasing:
      intent: Authorize a metric image upload for an alert
      effect: write
      questions:
      - What is the Workhorse authorize step before uploading an alert metric image?
      - Is there a pre-upload authorization call for attaching images to alerts?
      instructions:
      - text: Authorize a metric image file upload for alert {alert_iid} in project {id}.
        slots:
          alert_iid: path.alert_iid
          id: path.id
      - text: Run the Workhorse upload authorization for alert {alert_iid} on {id}.
        slots:
          alert_iid: path.alert_iid
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List CI jobs in a project
      effect: read
      questions:
      - How do I see all the CI/CD jobs that have run in a project?
      - Can I list only failed or pending jobs for a project?
      instructions:
      - text: List the CI jobs in project {id}.
        slots:
          id: path.id
      - text: Show jobs in project {id} with status {scope}.
        slots:
          id: path.id
          scope: query.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/jobs/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single CI job
      effect: read
      questions:
      - How do I check the status and details of one CI job by its ID?
      - What information does GitLab return for a specific pipeline job?
      instructions:
      - text: Show job {job_id} in project {id}.
        slots:
          job_id: path.job_id
          id: path.id
      - text: Get the status of CI job {job_id} from project {id}.
        slots:
          job_id: path.job_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v4/projects/{id}/jobs/{job_id}/play'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a manual CI job
      effect: write
      questions:
      - How do I start a manual job that's waiting in a pipeline?
      - Can I pass custom variables when I play a manual job?
      instructions:
      - text: Play manual job {job_id} in project {id}.
        slots:
          job_id: path.job_id
          id: path.id
      - text: Run manual job {job_id} in {id} with variables {job_variables_attributes}.
        slots:
          job_id: path.job_id
          id: path.id
          job_variables_attributes: query.job_variables_attributes
      method: generated
      generated: '2026-09-26'