# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Test Observer Artefact Matching Rules API
  version: 1.0.0
extends: openapi/canonical-artefact-matching-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: 5
- target: $.paths['/v1/artefact-matching-rules'].get
  update:
    x-apievangelist-phrasing:
      intent: List artefact matching rules
      effect: read
      questions:
      - Which rules decide which team reviews an artefact in Test Observer?
      - Can I list only the matching rules for the snap or deb family?
      instructions:
      - text: List all artefact matching rules.
      - text: List artefact matching rules for family {family}.
        slots:
          family: query.family
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/artefact-matching-rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an artefact matching rule
      effect: write
      questions:
      - How do I route artefacts of a given family to my team for review?
      - Can a matching rule target a specific track, series or release?
      instructions:
      - text: Create a matching rule for family {family} assigned to teams {team_ids}.
        slots:
          family: requestBody.family
          team_ids: requestBody.team_ids
      - text: Add a rule matching {family} artefacts on track {track} for teams {team_ids}.
        slots:
          family: requestBody.family
          track: requestBody.track
          team_ids: requestBody.team_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/artefact-matching-rules/{rule_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an artefact matching rule
      effect: read
      questions:
      - What criteria and teams does a particular matching rule have?
      - Can I look up one artefact matching rule by its ID?
      instructions:
      - text: Show artefact matching rule {rule_id}.
        slots:
          rule_id: path.rule_id
      - text: Get the teams attached to matching rule {rule_id}.
        slots:
          rule_id: path.rule_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/artefact-matching-rules/{rule_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an artefact matching rule
      effect: destructive
      questions:
      - How do I remove an artefact matching rule?
      - Can I stop a rule from assigning artefacts to a team by deleting it?
      instructions:
      - text: Delete artefact matching rule {rule_id}.
        slots:
          rule_id: path.rule_id
      - text: Remove matching rule {rule_id}.
        slots:
          rule_id: path.rule_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/artefact-matching-rules/{rule_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an artefact matching rule
      effect: write
      questions:
      - How do I change which teams an existing matching rule assigns?
      - Can I narrow an existing rule to a different stage or branch?
      instructions:
      - text: Reassign matching rule {rule_id} to teams {team_ids}.
        slots:
          rule_id: path.rule_id
          team_ids: requestBody.team_ids
      - text: Change rule {rule_id} to match stage {stage}.
        slots:
          rule_id: path.rule_id
          stage: requestBody.stage
      method: generated
      generated: '2026-09-26'