# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Scores API
  version: 1.0.0
extends: openapi/harness-scores-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: 6
- target: $.paths['/v1/scores/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize scorecard scores for an entity
      effect: read
      questions:
      - How is a catalog component doing across all its scorecards?
      - What's the headline score summary for one service in the developer portal?
      instructions:
      - text: Summarize the scorecard results for entity {entity_identifier}.
        slots:
          entity_identifier: query.entity_identifier
      - text: Give me the score summary across scorecards for {entity_identifier}.
        slots:
          entity_identifier: query.entity_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/scores'].get
  update:
    x-apievangelist-phrasing:
      intent: Get per-scorecard scores for an entity
      effect: read
      questions:
      - What score does each scorecard give a particular catalog entity?
      - Which checks is my service failing on its scorecards?
      instructions:
      - text: Show each scorecard's score for entity {entity_identifier}.
        slots:
          entity_identifier: query.entity_identifier
      - text: List scorecard scores and checks for {entity_identifier}.
        slots:
          entity_identifier: query.entity_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/scores/aggregate'].post
  update:
    x-apievangelist-phrasing:
      intent: Aggregate scores across catalog entities
      effect: read
      questions:
      - What's the average scorecard score across all our components of a given kind?
      - Can I aggregate scores by owner, tag or lifecycle?
      instructions:
      - text: Aggregate scorecard scores for catalog entities of kind {kind}.
        slots:
          kind: requestBody.kind
      - text: Show aggregated scores for {kind} entities owned by {owners} in lifecycle {lifecycle}.
        slots:
          kind: requestBody.kind
          owners: requestBody.owners
          lifecycle: requestBody.lifecycle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/scores/graph'].get
  update:
    x-apievangelist-phrasing:
      intent: Get check status data for score graphs
      effect: read
      questions:
      - How have an entity's scorecard checks trended over time?
      - Can I get graph data for one scorecard on a specific component?
      instructions:
      - text: Get check status graph data for entity {entity_identifier}.
        slots:
          entity_identifier: query.entity_identifier
      - text: Chart scorecard {scorecard_identifier} results for {entity_identifier}.
        slots:
          scorecard_identifier: query.scorecard_identifier
          entity_identifier: query.entity_identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/scores/recalibrate'].post
  update:
    x-apievangelist-phrasing:
      intent: Recalculate scorecard scores
      effect: write
      questions:
      - I fixed a failing check — can I force the scorecard to recompute now?
      - Is there a way to trigger score recalibration for an entity's scorecard?
      instructions:
      - text: Recalibrate scores for {identifiers}.
        slots:
          identifiers: requestBody.identifiers
      - text: Trigger a scorecard recalculation for entity and scorecard {identifiers}.
        slots:
          identifiers: requestBody.identifiers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/scores/recalibrate/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a score recalibration's progress
      effect: read
      questions:
      - Has the scorecard recalculation I kicked off finished yet?
      - What's the status of a pending score computation?
      instructions:
      - text: Check the recalibration status for {identifiers}.
        slots:
          identifiers: requestBody.identifiers
      - text: Tell me whether score recomputation for {identifiers} is done.
        slots:
          identifiers: requestBody.identifiers
      method: generated
      generated: '2026-09-26'