# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Secrets API
  version: 1.0.0
extends: openapi/harness-secrets-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: 14
- target: $.paths['/ng/api/v2/secrets/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count the secrets in a scope
      effect: read
      questions:
      - How many secrets exist under a given org or project?
      - Can I get just a secret count without listing them?
      instructions:
      - text: Count the secrets under scope {parent_id}.
        slots:
          parent_id: query.parentUniqueId
      - text: Tell me how many secrets account {account} has in scope {parent_id}.
        slots:
          account: query.accountIdentifier
          parent_id: query.parentUniqueId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets'].get
  update:
    x-apievangelist-phrasing:
      intent: List secrets with query-string filters
      effect: read
      questions:
      - What secrets are stored in my Harness project?
      - Can I list secrets from every sub-scope under an org at once?
      - Which secrets live in a particular secret manager?
      instructions:
      - text: List the secrets in project {project} using a simple GET filter.
        slots:
          project: query.projectIdentifier
      - text: Show secrets of type {type} whose name matches {search}.
        slots:
          type: query.type
          search: query.searchTerm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a secret
      effect: write
      questions:
      - How do I store a new text secret at the project level?
      - Can I create a secret that only I can see?
      instructions:
      - text: Create secret {secret} in project {project}.
        slots:
          secret: requestBody.secret
          project: query.projectIdentifier
      - text: Add a private secret {secret} for my use only.
        slots:
          secret: requestBody.secret
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file as a secret
      effect: write
      questions:
      - Can I upload a certificate or key file as a secret?
      - What's the way to store a whole file as an encrypted secret?
      instructions:
      - text: Upload {file} as a new secret file.
        slots:
          file: requestBody.file
      - text: Create a secret file from {file} in project {project}.
        slots:
          file: requestBody.file
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/yaml'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a secret from YAML
      effect: write
      questions:
      - Can I define a new secret using a YAML document?
      - Is there a YAML-based way to create secrets for config-as-code?
      instructions:
      - text: Create a secret from this YAML definition {secret}.
        slots:
          secret: requestBody.secret
      - text: Add the YAML-defined secret {secret} to project {project}.
        slots:
          secret: requestBody.secret
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a secret by its identifier
      effect: read
      questions:
      - Can I look up the details of one secret by its ID?
      - What metadata is stored for a specific secret?
      instructions:
      - text: Get secret {identifier}.
        slots:
          identifier: path.identifier
      - text: Show the details of secret {identifier} in project {project}.
        slots:
          identifier: path.identifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/{identifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a secret
      effect: write
      questions:
      - How do I rotate the value of an existing text secret?
      - Can I change an existing secret's settings with a JSON body?
      instructions:
      - text: Update secret {identifier} with {secret}.
        slots:
          identifier: path.identifier
          secret: requestBody.secret
      - text: Replace the stored definition of secret {identifier} in project {project}.
        slots:
          identifier: path.identifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a secret
      effect: destructive
      questions:
      - Can I force-delete a secret that is still referenced somewhere?
      - What's the way to permanently remove a secret?
      instructions:
      - text: Delete secret {identifier}.
        slots:
          identifier: path.identifier
      - text: Force delete secret {identifier} even if it's in use.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/list/secrets'].post
  update:
    x-apievangelist-phrasing:
      intent: Search secrets by name, tags or description
      effect: read
      questions:
      - Can I find secrets by their tags or description?
      - Which secrets have a name that contains a given word?
      instructions:
      - text: Find secrets named {name}.
        slots:
          name: requestBody.secretName
      - text: Search secrets tagged {tags} with description matching {description}.
        slots:
          tags: requestBody.tags
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/list'].post
  update:
    x-apievangelist-phrasing:
      intent: List secrets with a filter body by ID or category
      effect: read
      questions:
      - Can I fetch a batch of secrets by a list of identifiers?
      - Which secrets belong to a given source category?
      instructions:
      - text: Fetch the secrets with identifiers {identifiers}.
        slots:
          identifiers: requestBody.identifiers
      - text: List secrets in source category {category} via the filter body.
        slots:
          category: requestBody.sourceCategory
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/files/{identifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a secret file
      effect: write
      questions:
      - Can I upload a new version of a file stored as a secret?
      - How would I swap out an expired certificate held in a secret file?
      instructions:
      - text: Replace secret file {identifier} with {file}.
        slots:
          identifier: path.identifier
          file: requestBody.file
      - text: Upload new contents for secret file {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/{identifier}/yaml'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a secret using YAML
      effect: write
      questions:
      - Can I edit an existing secret by sending YAML?
      - Is there a YAML update path for secrets I manage as code?
      instructions:
      - text: Update secret {identifier} from YAML {secret}.
        slots:
          identifier: path.identifier
          secret: requestBody.secret
      - text: Apply the YAML {secret} to existing secret {identifier}.
        slots:
          secret: requestBody.secret
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate that a secret works
      effect: read
      questions:
      - Can I test whether a secret resolves correctly before using it?
      - Is there a check that a stored secret reference is valid?
      instructions:
      - text: Validate secret {identifier} of type {type}.
        slots:
          identifier: query.identifier
          type: requestBody.type
      - text: Check that secret {identifier} is usable.
        slots:
          identifier: query.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/v2/secrets/validateUniqueIdentifier/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a secret identifier is not taken
      effect: read
      questions:
      - Is a secret ID I want to use already taken?
      - Can I confirm an identifier is unique before creating a secret?
      instructions:
      - text: Check whether secret identifier {identifier} is available.
        slots:
          identifier: path.identifier
      - text: Confirm {identifier} is unique in project {project}.
        slots:
          identifier: path.identifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'