# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Certificates API
  version: 1.0.0
extends: openapi/microsoft-azure-certificates-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: 26
- target: $.paths['/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: List certificates added to a Batch account
      effect: read
      questions:
      - Which certificates have been added to my Azure Batch account?
      - Can I filter the Batch account certificate list and cap how many come back?
      instructions:
      - text: List every certificate added to my Batch account.
      - text: List up to {max} Batch account certificates matching {filter}.
        slots:
          max: query.maxresults
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a certificate to a Batch account
      effect: write
      questions:
      - How do I add a certificate to an Azure Batch account so pools can use it?
      - What do I need to supply when uploading a certificate to Batch — thumbprint, algorithm and data?
      instructions:
      - text: Add a certificate with thumbprint {thumbprint} ({algorithm}) to my Batch account using data {data}.
        slots:
          thumbprint: requestBody.thumbprint
          algorithm: requestBody.thumbprintAlgorithm
          data: requestBody.data
      - text: Upload a {format} certificate to the Batch account with thumbprint {thumbprint}, algorithm {algorithm}, data {data} and password {password}.
        slots:
          format: requestBody.certificateFormat
          thumbprint: requestBody.thumbprint
          algorithm: requestBody.thumbprintAlgorithm
          data: requestBody.data
          password: requestBody.password
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates/{certificate-name}/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new Key Vault certificate version
      effect: write
      questions:
      - Can I create a new certificate in Key Vault from a certificate policy?
      - What happens when I create a certificate name that already exists in the vault — does it add a new version?
      instructions:
      - text: Create a new vault certificate named {certificate_name}.
        slots:
          certificate_name: path.certificate-name
      - text: Create vault certificate {certificate_name} using policy {policy} and tags {tags}.
        slots:
          certificate_name: path.certificate-name
          policy: requestBody.policy
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: List certificates in an Azure Sphere catalog
      effect: read
      questions:
      - Which certificates belong to my Azure Sphere catalog?
      - Can I page through Azure Sphere catalog certificates with top and skip?
      instructions:
      - text: List the certificates in Azure Sphere catalog {catalog}.
        slots:
          catalog: path.catalogName
      - text: Show the first {top} certificates in Sphere catalog {catalog} that match {filter}.
        slots:
          top: query.$top
          catalog: path.catalogName
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/certificates/{serialNumber}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an Azure Sphere catalog certificate by serial
      effect: read
      questions:
      - What are the details of a specific Azure Sphere certificate by its serial number?
      - Can I look up one Sphere catalog certificate without listing them all?
      instructions:
      - text: Get Sphere catalog {catalog} certificate with serial number {serial}.
        slots:
          catalog: path.catalogName
          serial: path.serialNumber
      - text: Show me certificate {serial} from Azure Sphere catalog {catalog}.
        slots:
          serial: path.serialNumber
          catalog: path.catalogName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/certificates/{serialNumber}/retrieveCertChain'].post
  update:
    x-apievangelist-phrasing:
      intent: Retrieve the chain for an Azure Sphere certificate
      effect: read
      questions:
      - How can I get the full certificate chain for an Azure Sphere catalog certificate?
      - Can I download the issuing chain behind a Sphere certificate serial number?
      instructions:
      - text: Retrieve the certificate chain for serial {serial} in Sphere catalog {catalog}.
        slots:
          serial: path.serialNumber
          catalog: path.catalogName
      - text: Fetch the cert chain of Azure Sphere certificate {serial} from catalog {catalog}.
        slots:
          serial: path.serialNumber
          catalog: path.catalogName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/certificates/{serialNumber}/retrieveProofOfPossessionNonce'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a proof-of-possession nonce for a Sphere cert
      effect: read
      questions:
      - Where do I get a proof of possession nonce for an Azure Sphere catalog certificate?
      - Can I request a proof-of-possession nonce against a specific Sphere certificate serial?
      instructions:
      - text: Retrieve the proof-of-possession nonce for Sphere certificate {serial} in catalog {catalog} using nonce {nonce}.
        slots:
          serial: path.serialNumber
          catalog: path.catalogName
          nonce: requestBody.proofOfPossessionNonce
      - text: Get a possession nonce response for certificate {serial} in Sphere catalog {catalog} with {nonce}.
        slots:
          serial: path.serialNumber
          catalog: path.catalogName
          nonce: requestBody.proofOfPossessionNonce
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates(thumbprintAlgorithm={thumbprintAlgorithm},thumbprint={thumbprint})/canceldelete'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a failed Batch certificate deletion
      effect: write
      questions:
      - My Batch certificate is stuck in deleteFailed because a pool still uses it — can I keep it active?
      - How do I undo a failed deletion of a Batch account certificate?
      instructions:
      - text: Cancel the failed deletion of Batch certificate {thumbprint} ({algorithm}).
        slots:
          thumbprint: path.thumbprint
          algorithm: path.thumbprintAlgorithm
      - text: Restore Batch certificate {algorithm} {thumbprint} to active after its delete failed.
        slots:
          algorithm: path.thumbprintAlgorithm
          thumbprint: path.thumbprint
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates(thumbprintAlgorithm={thumbprintAlgorithm},thumbprint={thumbprint})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Batch certificate by thumbprint
      effect: read
      questions:
      - What's the state of a Batch account certificate given its thumbprint?
      - Can I fetch only selected properties of one Batch certificate?
      instructions:
      - text: Get Batch certificate {thumbprint} using algorithm {algorithm}.
        slots:
          thumbprint: path.thumbprint
          algorithm: path.thumbprintAlgorithm
      - text: Show the {select} fields of Batch certificate {algorithm} {thumbprint}.
        slots:
          select: query.$select
          algorithm: path.thumbprintAlgorithm
          thumbprint: path.thumbprint
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates(thumbprintAlgorithm={thumbprintAlgorithm},thumbprint={thumbprint})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a certificate from a Batch account
      effect: destructive
      questions:
      - Why can't I delete a Batch certificate that a pool or compute node still uses?
      - How do I remove a certificate from my Azure Batch account by thumbprint?
      instructions:
      - text: Delete Batch certificate {thumbprint} ({algorithm}) from the account.
        slots:
          thumbprint: path.thumbprint
          algorithm: path.thumbprintAlgorithm
      - text: Remove the {algorithm} certificate {thumbprint} from my Batch account.
        slots:
          algorithm: path.thumbprintAlgorithm
          thumbprint: path.thumbprint
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: List certificates on an IoT hub
      effect: read
      questions:
      - Which X.509 certificates are uploaded to my IoT hub?
      - Can I see all CA certificates registered on an Azure IoT Hub?
      instructions:
      - text: List the certificates on IoT hub {hub} in resource group {group}.
        slots:
          hub: path.resourceName
          group: path.resourceGroupName
      - text: Show every certificate on IoT hub {hub} in group {group} under subscription {subscription}.
        slots:
          hub: path.resourceName
          group: path.resourceGroupName
          subscription: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one X.509 certificate on an IoT hub
      effect: read
      questions:
      - How do I check the status of one CA certificate uploaded to my IoT hub?
      - Is a specific IoT hub certificate verified yet, and when does it expire?
      instructions:
      - text: Show certificate {certificateName} on IoT hub {resourceName}.
        slots:
          certificateName: path.certificateName
          resourceName: path.resourceName
      - text: Get the details of IoT hub {resourceName} certificate {certificateName}.
        slots:
          resourceName: path.resourceName
          certificateName: path.certificateName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Upload a certificate to an IoT hub
      effect: write
      questions:
      - How do I upload a CA certificate to my IoT hub for device authentication?
      - Can I replace an X.509 certificate that is already on an IoT hub?
      instructions:
      - text: Upload certificate {certificate} to IoT hub {resourceName} in resource group {rg}.
        slots:
          certificate: path.certificateName
          resourceName: path.resourceName
          rg: path.resourceGroupName
      - text: Replace IoT hub certificate {certificate} with {properties}.
        slots:
          certificate: path.certificateName
          properties: requestBody.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an X.509 certificate from an IoT hub
      effect: destructive
      questions:
      - Can I remove a CA certificate from my IoT hub?
      - What ETag do I need to supply to delete an IoT hub certificate?
      instructions:
      - text: Delete certificate {certificateName} from IoT hub {resourceName}.
        slots:
          certificateName: path.certificateName
          resourceName: path.resourceName
      - text: Remove the X.509 certificate {certificateName} from hub {resourceName} using ETag {etag}.
        slots:
          certificateName: path.certificateName
          resourceName: path.resourceName
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}/generateVerificationCode'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a verification code for an IoT hub cert
      effect: write
      questions:
      - How do I get a verification code to prove I own a CA certificate on IoT Hub?
      - What code do I sign into a leaf certificate for the proof-of-possession flow?
      instructions:
      - text: Generate a verification code for certificate {certificate} on IoT hub {hub} in group {group}, ETag {etag}.
        slots:
          certificate: path.certificateName
          hub: path.resourceName
          group: path.resourceGroupName
          etag: header.If-Match
      - text: Start proof of possession for IoT hub {hub} cert {certificate} in subscription {subscription}, group {group}, ETag {etag}.
        slots:
          hub: path.resourceName
          certificate: path.certificateName
          subscription: path.subscriptionId
          group: path.resourceGroupName
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{resourceName}/certificates/{certificateName}/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify private key possession of an IoT hub cert
      effect: write
      questions:
      - How do I mark an uploaded IoT hub CA certificate as verified?
      - Can I submit the signed leaf certificate to prove private key possession?
      instructions:
      - text: Verify IoT hub {hub} certificate {certificate} in group {group} with leaf cert {leaf}, ETag {etag}.
        slots:
          hub: path.resourceName
          certificate: path.certificateName
          group: path.resourceGroupName
          leaf: requestBody.certificate
          etag: header.If-Match
      - text: Submit leaf certificate {leaf} to prove possession of {certificate} on hub {hub} (subscription {subscription}, group {group}, ETag {etag}).
        slots:
          leaf: requestBody.certificate
          certificate: path.certificateName
          hub: path.resourceName
          subscription: path.subscriptionId
          group: path.resourceGroupName
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: List App Service certificates in a resource group
      effect: read
      questions:
      - Which App Service certificates exist in a given resource group?
      - Can I list the web app certificates in one resource group of my subscription?
      instructions:
      - text: List the App Service certificates in resource group {group}.
        slots:
          group: path.resourceGroupName
      - text: Show web certificates in group {group} of subscription {subscription}.
        slots:
          group: path.resourceGroupName
          subscription: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/certificates/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an App Service certificate by name
      effect: read
      questions:
      - What are the details of one App Service certificate in my resource group?
      - Can I fetch a web app certificate by its name?
      instructions:
      - text: Get App Service certificate {name} in group {group}.
        slots:
          name: path.name
          group: path.resourceGroupName
      - text: Show the web certificate {name} from subscription {subscription}, resource group {group}.
        slots:
          name: path.name
          subscription: path.subscriptionId
          group: path.resourceGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/certificates/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace an App Service certificate
      effect: write
      questions:
      - How do I create a new App Service certificate in a resource group?
      - Which region do I have to give when putting a web app certificate?
      instructions:
      - text: Create App Service certificate {name} in group {group} of subscription {subscription}, located in {location}.
        slots:
          name: path.name
          group: path.resourceGroupName
          location: requestBody.location
          subscription: path.subscriptionId
      - text: Put web certificate {name} in {location} under group {group} with properties {properties}.
        slots:
          name: path.name
          location: requestBody.location
          group: path.resourceGroupName
          properties: requestBody.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/certificates/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an App Service certificate
      effect: destructive
      questions:
      - How can I delete an App Service certificate I no longer use?
      - Can I remove a web app certificate by name from a resource group?
      instructions:
      - text: Delete App Service certificate {name} in resource group {group}.
        slots:
          name: path.name
          group: path.resourceGroupName
      - text: Remove web certificate {name} from group {group} in subscription {subscription}.
        slots:
          name: path.name
          group: path.resourceGroupName
          subscription: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/certificates/{name}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch an existing App Service certificate
      effect: write
      questions:
      - Can I change the tags on an existing App Service certificate without recreating it?
      - What fields can I patch on a web app certificate?
      instructions:
      - text: Patch App Service certificate {name} in subscription {subscription}, group {group} ({location}) with tags {tags}.
        slots:
          name: path.name
          group: path.resourceGroupName
          location: requestBody.location
          tags: requestBody.tags
          subscription: path.subscriptionId
      - text: Update existing web certificate {name} in {group}, region {location}, setting properties {properties}.
        slots:
          name: path.name
          group: path.resourceGroupName
          location: requestBody.location
          properties: requestBody.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/csrs'].get
  update:
    x-apievangelist-phrasing:
      intent: List certificate signing requests in a group
      effect: read
      questions:
      - Which certificate signing requests have I created in a resource group?
      - Can I list all CSRs for web apps in my subscription's resource group?
      instructions:
      - text: List the certificate signing requests in resource group {group}.
        slots:
          group: path.resourceGroupName
      - text: Show all CSRs in group {group} for subscription {subscription}.
        slots:
          group: path.resourceGroupName
          subscription: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/csrs/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a certificate signing request by name
      effect: read
      questions:
      - What does a specific certificate signing request contain?
      - Can I retrieve one CSR by name from a resource group?
      instructions:
      - text: Get certificate signing request {name} in group {group}.
        slots:
          name: path.name
          group: path.resourceGroupName
      - text: Show CSR {name} from subscription {subscription}, resource group {group}.
        slots:
          name: path.name
          subscription: path.subscriptionId
          group: path.resourceGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/csrs/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a certificate signing request
      effect: write
      questions:
      - How do I create a certificate signing request for an App Service certificate?
      - Which location must I set when creating a new CSR?
      instructions:
      - text: Create certificate signing request {name} in subscription {subscription}, group {group}, located in {location}.
        slots:
          name: path.name
          group: path.resourceGroupName
          location: requestBody.location
          subscription: path.subscriptionId
      - text: Put CSR {name} in {location} under group {group} with properties {properties}.
        slots:
          name: path.name
          location: requestBody.location
          group: path.resourceGroupName
          properties: requestBody.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/csrs/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a certificate signing request
      effect: destructive
      questions:
      - Can I delete a certificate signing request I no longer need?
      - How do I get rid of an old CSR in a resource group?
      instructions:
      - text: Delete certificate signing request {name} in group {group}.
        slots:
          name: path.name
          group: path.resourceGroupName
      - text: Remove CSR {name} from group {group} in subscription {subscription}.
        slots:
          name: path.name
          group: path.resourceGroupName
          subscription: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/csrs/{name}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch an existing certificate signing request
      effect: write
      questions:
      - Can I update the tags on an existing certificate signing request?
      - What can I change on a CSR after it has been created?
      instructions:
      - text: Patch certificate signing request {name} in subscription {subscription}, group {group} ({location}) with tags {tags}.
        slots:
          name: path.name
          group: path.resourceGroupName
          location: requestBody.location
          tags: requestBody.tags
          subscription: path.subscriptionId
      - text: Update existing CSR {name} in {group}, region {location}, setting properties {properties}.
        slots:
          name: path.name
          group: path.resourceGroupName
          location: requestBody.location
          properties: requestBody.properties
      method: generated
      generated: '2026-09-26'