# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Entities API
  version: 1.0.0
extends: openapi/harness-entities-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: 17
- target: $.paths['/v1/entities'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog entities with filters
      effect: read
      questions:
      - Which catalog entities do I own across my projects?
      - Can I filter the software catalog by kind, lifecycle or tags?
      - How do I page through every service in the IDP catalog?
      instructions:
      - text: List catalog entities of kind {kind} owned by {owner}.
        slots:
          kind: query.kind
          owner: query.owner
      - text: Show my favorite catalog entities with lifecycle {lifecycle}.
        slots:
          lifecycle: query.lifecycle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a catalog entity from YAML
      effect: write
      questions:
      - How do I register a new service in the catalog from its YAML definition?
      - Can I dry-run an entity creation to validate the YAML first?
      instructions:
      - text: 'Create a catalog entity from this YAML: {yaml}.'
        slots:
          yaml: requestBody.yaml
      - text: Dry-run creating an entity in project {project} with YAML {yaml}.
        slots:
          project: query.projectIdentifier
          yaml: requestBody.yaml
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/bulk-field-update'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk-update one field across catalog entities
      effect: write
      questions:
      - Can I change the owner on many catalog entities at once?
      - Is there a way to update a single field on every entity matching a filter?
      instructions:
      - text: Bulk-update entities {entity_refs} with field change {properties}.
        slots:
          entity_refs: requestBody.entityRefs
          properties: requestBody.properties
      - text: Submit a bulk field update of {properties} for all entities matching filter {filter}.
        slots:
          properties: requestBody.properties
          filter: requestBody.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/bulk-field-update/{operation-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a bulk field update's status
      effect: read
      questions:
      - Has my bulk owner change on the catalog finished yet?
      - Where can I see the result of a bulk field update I submitted?
      instructions:
      - text: Get the status of bulk field update operation {operation_id}.
        slots:
          operation_id: path.operation-id
      - text: Check whether bulk update {operation_id} succeeded.
        slots:
          operation_id: path.operation-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/by-refs'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch catalog entities by their refs
      effect: read
      questions:
      - Can I look up several catalog entities at once from a list of entity references?
      - What's the way to fetch specific entities by ref while still applying filters?
      instructions:
      - text: Fetch catalog entities matching refs {entity_refs}.
        slots:
          entity_refs: requestBody.entity_refs
      - text: Look up entities {entity_refs} and keep only those tagged {tags}.
        slots:
          entity_refs: requestBody.entity_refs
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import a catalog entity from Git
      effect: write
      questions:
      - Can I import an existing entity YAML file from a Git repo into the catalog?
      - Does importing an entity work with a Harness Code repository?
      instructions:
      - text: Import the entity at {file_path} in repo {repo} on branch {branch}.
        slots:
          file_path: requestBody.file_path
          repo: requestBody.repo_name
          branch: requestBody.branch_name
      - text: Import a catalog entity from Git using connector {connector}.
        slots:
          connector: requestBody.connector_ref
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: View catalog entities grouped by scope
      effect: read
      questions:
      - Can I see catalog entities organized by account, organization and project?
      - Which entities sit ungrouped at each level of my hierarchy?
      instructions:
      - text: Show catalog entities grouped by scope, filtered to kind {kind}.
        slots:
          kind: query.kind
      - text: Group my owned entities by organization and project.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/move/{scope}/{kind}/{identifier}'].post
  update:
    x-apievangelist-phrasing:
      intent: Move an inline catalog entity to Git
      effect: write
      questions:
      - How do I move an inline catalog entity so it's stored in Git?
      - Can I convert an entity from inline storage to remote?
      instructions:
      - text: Move {kind} entity {identifier} in scope {scope} to remote using Git details {git_details}.
        slots:
          kind: path.kind
          identifier: path.identifier
          scope: path.scope
          git_details: requestBody.git_details
      - text: Move entity {identifier} from inline to remote with move type {move_type}.
        slots:
          identifier: path.identifier
          move_type: requestBody.entity_move_operation_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/git-metadata/{scope}/{kind}/{identifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update Git metadata for a remote entity
      effect: write
      questions:
      - Can I point a remote catalog entity at a different repo or file path?
      - How do I change the branch recorded for an entity stored in Git?
      instructions:
      - text: Update Git metadata of {kind} entity {identifier} in scope {scope} to repo {repo}.
        slots:
          kind: path.kind
          identifier: path.identifier
          scope: path.scope
          repo: requestBody.repo_name
      - text: Change the Git file path of remote entity {identifier} to {file_path}.
        slots:
          identifier: path.identifier
          file_path: requestBody.file_path
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/convert/{option}'].post
  update:
    x-apievangelist-phrasing:
      intent: Convert entity YAML between Backstage and Harness
      effect: read
      questions:
      - Can I turn a Backstage catalog-info YAML into Harness entity format?
      - Is there a converter for entity definitions going the other way, Harness to Backstage?
      instructions:
      - text: 'Convert this entity YAML using option {option}: {yaml}.'
        slots:
          option: path.option
          yaml: requestBody.yaml
      - text: Convert my Backstage YAML {yaml} to Harness format with option {option}.
        slots:
          option: path.option
          yaml: requestBody.yaml
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/{scope}/{kind}/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a catalog entity's full details
      effect: read
      questions:
      - What do the full YAML and relationships of one catalog entity look like?
      - Can I read an entity's definition from a specific Git branch?
      instructions:
      - text: Get the details of {kind} entity {identifier} in scope {scope}.
        slots:
          kind: path.kind
          identifier: path.identifier
          scope: path.scope
      - text: Show entity {identifier} as stored on branch {branch}.
        slots:
          identifier: path.identifier
          branch: query.branch_name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/{scope}/{kind}/{identifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a catalog entity's definition
      effect: write
      questions:
      - How do I overwrite an existing catalog entity with new YAML?
      - Will updating an entity create it if it doesn't exist yet?
      instructions:
      - text: Update {kind} entity {identifier} in scope {scope} with YAML {yaml}.
        slots:
          kind: path.kind
          identifier: path.identifier
          scope: path.scope
          yaml: requestBody.yaml
      - text: Replace the definition of entity {identifier} with {yaml}.
        slots:
          identifier: path.identifier
          yaml: requestBody.yaml
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/{scope}/{kind}/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a catalog entity
      effect: destructive
      questions:
      - Can I permanently remove a service from the software catalog?
      - What happens to references when a catalog entity is deleted?
      instructions:
      - text: Delete {kind} entity {identifier} in scope {scope}.
        slots:
          kind: path.kind
          identifier: path.identifier
          scope: path.scope
      - text: Permanently remove catalog entity {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/kinds'].get
  update:
    x-apievangelist-phrasing:
      intent: List supported entity kinds with counts
      effect: read
      questions:
      - Which entity kinds does the catalog support, and how many of each exist?
      - Can I get display names and descriptions for all entity kinds?
      instructions:
      - text: List entity kinds and their counts for account {account}.
        slots:
          account: query.accountIdentifier
      - text: Show the entity kinds available in project {project}.
        slots:
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/filters'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the available entity filter options
      effect: read
      questions:
      - What filter values can I use when browsing the catalog?
      - Which owners and lifecycles show up as filters for a given kind?
      instructions:
      - text: Get catalog filter options for account {account}.
        slots:
          account: query.accountIdentifier
      - text: Show the available filter values for entity kind {kind}.
        slots:
          kind: query.kind
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/filters'].post
  update:
    x-apievangelist-phrasing:
      intent: Get filter options for a set of entity refs
      effect: read
      questions:
      - Can I get filter options limited to a specific list of entity references?
      - Which filter values apply only to the entities I pass in?
      instructions:
      - text: Get filter options for entities {entity_refs} in account {account}.
        slots:
          entity_refs: requestBody.entity_refs
          account: query.accountIdentifier
      - text: Compute filter values scoped to refs {entity_refs}.
        slots:
          entity_refs: requestBody.entity_refs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/entities/json-schema'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the JSON Schema for entity definitions
      effect: read
      questions:
      - Is there a JSON Schema I can use to validate entity YAML before submitting it?
      - Can I get validation rules for just one entity kind?
      instructions:
      - text: Get the entity JSON Schema for kind {kind}.
        slots:
          kind: query.kind
      - text: Fetch the JSON Schema for validating catalog entity definitions.
      method: generated
      generated: '2026-09-26'