# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Amazon Manager Secrets API
  version: 1.0.0
extends: openapi/amazon-secrets-manager-secrets-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/'].post
  update:
    x-apievangelist-phrasing:
      intent: Store a new secret
      effect: write
      questions:
      - How do I store a new API key or database password in AWS Secrets Manager?
      - Can I encrypt a brand-new secret with my own KMS key instead of the default?
      - Which kinds of data can a new secret hold, text or binary?
      instructions:
      - text: Create a secret named {Name} holding {SecretString}.
        slots:
          Name: requestBody.Name
          SecretString: requestBody.SecretString
      - text: Create a new secret {Name} described as {Description}, encrypted with KMS key {KmsKeyId}.
        slots:
          Name: requestBody.Name
          Description: requestBody.Description
          KmsKeyId: requestBody.KmsKeyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/#GetSecretValue'].post
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a secret's value
      effect: read
      questions:
      - How do I read the actual password stored inside a secret?
      - Can I fetch the value of an earlier version of a secret by its staging label?
      instructions:
      - text: Get the decrypted value of secret {SecretId}.
        slots:
          SecretId: requestBody.SecretId
      - text: Fetch the secret value of {SecretId} at staging label {VersionStage}.
        slots:
          SecretId: requestBody.SecretId
          VersionStage: requestBody.VersionStage
      - text: Read the contents of version {VersionId} of secret {SecretId}.
        slots:
          VersionId: requestBody.VersionId
          SecretId: requestBody.SecretId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/#PutSecretValue'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new version of a secret's value
      effect: write
      questions:
      - How do I store a new value for an existing secret as a fresh version?
      - Can I attach staging labels to a new secret version when I save it?
      instructions:
      - text: Put a new version with value {SecretString} on secret {SecretId}.
        slots:
          SecretString: requestBody.SecretString
          SecretId: requestBody.SecretId
      - text: Save a new version of secret {SecretId} and label it {VersionStages}.
        slots:
          SecretId: requestBody.SecretId
          VersionStages: requestBody.VersionStages
      method: generated
      generated: '2026-10-01'
- target: $.paths['/#UpdateSecret'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a secret's details
      effect: write
      questions:
      - How can I change the description of a secret I already created?
      - Can I switch an existing secret to a different KMS encryption key?
      instructions:
      - text: Change the description of secret {SecretId} to {Description}.
        slots:
          SecretId: requestBody.SecretId
          Description: requestBody.Description
      - text: Re-encrypt existing secret {SecretId} with KMS key {KmsKeyId}.
        slots:
          SecretId: requestBody.SecretId
          KmsKeyId: requestBody.KmsKeyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/#DeleteSecret'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a secret
      effect: destructive
      questions:
      - How do I delete a secret and all of its versions?
      - What is the shortest recovery window before a deleted secret is gone for good?
      - Is there a way to delete a secret immediately with no recovery window?
      instructions:
      - text: Delete secret {SecretId} with a {RecoveryWindowInDays}-day recovery window.
        slots:
          SecretId: requestBody.SecretId
          RecoveryWindowInDays: requestBody.RecoveryWindowInDays
      - text: Permanently delete secret {SecretId} right away without recovery.
        slots:
          SecretId: requestBody.SecretId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/#ListSecrets'].post
  update:
    x-apievangelist-phrasing:
      intent: List secrets in the account
      effect: read
      questions:
      - Which secrets are stored in my AWS account?
      - Can I filter the secrets list and sort it in a particular order?
      - Are secrets scheduled for deletion included when I list everything?
      instructions:
      - text: List all my secrets.
      - text: List up to {MaxResults} secrets matching filters {Filters}.
        slots:
          MaxResults: requestBody.MaxResults
          Filters: requestBody.Filters
      method: generated
      generated: '2026-10-01'
- target: $.paths['/#DescribeSecret'].post
  update:
    x-apievangelist-phrasing:
      intent: View a secret's metadata
      effect: read
      questions:
      - What rotation settings and tags does a particular secret have?
      - Can I see a secret's details without exposing its encrypted value?
      instructions:
      - text: Describe secret {SecretId}.
        slots:
          SecretId: requestBody.SecretId
      - text: Show the metadata for secret {SecretId}, not its value.
        slots:
          SecretId: requestBody.SecretId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/#RestoreSecret'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a secret scheduled for deletion
      effect: write
      questions:
      - How do I undo the deletion of a secret during its recovery window?
      - Can I get back a secret I marked for deletion by mistake?
      instructions:
      - text: Restore secret {SecretId} and cancel its scheduled deletion.
        slots:
          SecretId: requestBody.SecretId
      - text: Bring back deleted secret {SecretId}.
        slots:
          SecretId: requestBody.SecretId
      method: generated
      generated: '2026-10-01'