# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Rules API
  version: 1.0.0
extends: openapi/harness-rules-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: 10
- target: $.paths['/code/api/v1/repos/{repo_identifier}/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List a repository's protection rules
      effect: read
      questions:
      - What branch protection rules apply to one Harness Code repository?
      - Can I include rules a repo inherits from its project or org when listing them?
      instructions:
      - text: List the protection rules on repo {repo_identifier}.
        slots:
          repo_identifier: path.repo_identifier
      - text: Show protection rules of type {type} for repo {repo_identifier}, including inherited ones.
        slots:
          type: query.type
          repo_identifier: path.repo_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/repos/{repo_identifier}/rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a protection rule to a repository
      effect: write
      questions:
      - How do I protect the main branch of a single repo from direct pushes?
      - Can a repository rule match branches by pattern?
      instructions:
      - text: Add a protection rule {identifier} to repo {repo_identifier} matching pattern {pattern}.
        slots:
          identifier: requestBody.identifier
          repo_identifier: path.repo_identifier
          pattern: requestBody.pattern
      - text: Create a {type} rule on repo {repo_identifier} with definition {definition}.
        slots:
          type: requestBody.type
          repo_identifier: path.repo_identifier
          definition: requestBody.definition
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/repos/{repo_identifier}/rules/{rule_identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a repository protection rule
      effect: read
      questions:
      - What exactly does a given protection rule on my repo enforce?
      - Is a particular repo rule active or disabled?
      instructions:
      - text: Show protection rule {rule_identifier} on repo {repo_identifier}.
        slots:
          rule_identifier: path.rule_identifier
          repo_identifier: path.repo_identifier
      - text: Fetch the definition of repo rule {rule_identifier} in {repo_identifier}.
        slots:
          rule_identifier: path.rule_identifier
          repo_identifier: path.repo_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/repos/{repo_identifier}/rules/{rule_identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a repository protection rule
      effect: destructive
      questions:
      - Can I remove a branch protection rule from just one repository?
      - What happens to a repo's protection once its rule is deleted?
      instructions:
      - text: Delete protection rule {rule_identifier} from repo {repo_identifier}.
        slots:
          rule_identifier: path.rule_identifier
          repo_identifier: path.repo_identifier
      - text: Remove the repo-level rule {rule_identifier} in {repo_identifier}.
        slots:
          rule_identifier: path.rule_identifier
          repo_identifier: path.repo_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/repos/{repo_identifier}/rules/{rule_identifier}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a repository protection rule
      effect: write
      questions:
      - Can I temporarily disable a protection rule on a repo without deleting it?
      - How do I change which branches a repository rule covers?
      instructions:
      - text: Set repo rule {rule_identifier} in {repo_identifier} to state {state}.
        slots:
          rule_identifier: path.rule_identifier
          repo_identifier: path.repo_identifier
          state: requestBody.state
      - text: Change the branch pattern of rule {rule_identifier} on repo {repo_identifier} to {pattern}.
        slots:
          rule_identifier: path.rule_identifier
          repo_identifier: path.repo_identifier
          pattern: requestBody.pattern
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List protection rules for an account, org or project
      effect: read
      questions:
      - Which protection rules are defined at the org or project level rather than per repo?
      - Can I search account-wide protection rules by name?
      instructions:
      - text: List the protection rules defined at account {account} level.
        slots:
          account: query.accountIdentifier
      - text: Show protection rules for project {project} matching {query}.
        slots:
          project: query.projectIdentifier
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a protection rule for an account, org or project
      effect: write
      questions:
      - How do I enforce one branch protection rule across every repo in a project?
      - Can an org-wide rule target only some repositories?
      instructions:
      - text: Add an org-wide protection rule {identifier} matching branches {pattern}.
        slots:
          identifier: requestBody.identifier
          pattern: requestBody.pattern
      - text: Create a project-level rule {identifier} in account {account} that targets repos {repo_target}.
        slots:
          identifier: requestBody.identifier
          account: query.accountIdentifier
          repo_target: requestBody.repo_target
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/rules/{rule_identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an account, org or project protection rule
      effect: read
      questions:
      - What does a particular org-level protection rule enforce?
      - Which repos does a project-wide rule apply to?
      instructions:
      - text: Show the org or project level protection rule {rule_identifier}.
        slots:
          rule_identifier: path.rule_identifier
      - text: Fetch account-level rule {rule_identifier} from account {account}.
        slots:
          rule_identifier: path.rule_identifier
          account: query.accountIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/rules/{rule_identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an account, org or project protection rule
      effect: destructive
      questions:
      - Can I remove a protection rule that applies across a whole project?
      - Does deleting an org-level rule lift protection from every repo it covered?
      instructions:
      - text: Delete the org or project level protection rule {rule_identifier}.
        slots:
          rule_identifier: path.rule_identifier
      - text: Remove account-wide rule {rule_identifier} from account {account}.
        slots:
          rule_identifier: path.rule_identifier
          account: query.accountIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/code/api/v1/rules/{rule_identifier}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an account, org or project protection rule
      effect: write
      questions:
      - How do I change the repos targeted by a project-wide protection rule?
      - Can I switch an org-level rule to monitor-only state?
      instructions:
      - text: Set org or project level rule {rule_identifier} to state {state}.
        slots:
          rule_identifier: path.rule_identifier
          state: requestBody.state
      - text: Update account-wide rule {rule_identifier} to target repos {repo_target}.
        slots:
          rule_identifier: path.rule_identifier
          repo_target: requestBody.repo_target
      method: generated
      generated: '2026-09-26'