# 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 Topics API
  version: 1.0.0
extends: openapi/microsoft-azure-topics-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: 20
- target: $.paths['/topics/{topicName}:publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a CloudEvent to a namespace topic
      effect: write
      questions:
      - How can I publish a single CloudEvent to an Event Grid namespace topic?
      - Which CloudEvent fields are mandatory when publishing to a namespace topic?
      - Can I send binary event data as base64 when publishing a CloudEvent?
      instructions:
      - text: Publish a CloudEvent with id {id}, source {source} and type {type} to namespace topic {topicName}.
        slots:
          id: requestBody.id
          source: requestBody.source
          type: requestBody.type
          topicName: path.topicName
      - text: Send an event of type {type} with spec version {specversion} to topic {topicName}, subject {subject}.
        slots:
          type: requestBody.type
          specversion: requestBody.specversion
          topicName: path.topicName
          subject: requestBody.subject
      method: generated
      generated: '2026-09-26'
- target: $.paths['/topics/{topicName}/eventsubscriptions/{eventSubscriptionName}:receive'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a batch of events from a subscription
      effect: write
      questions:
      - How can I pull a batch of CloudEvents from a namespace topic event subscription?
      - Is there a cap on how many events I can receive in one pull, and how long it waits?
      instructions:
      - text: Receive up to {maxEvents} events from subscription {eventSubscriptionName} on topic {topicName}.
        slots:
          maxEvents: query.maxEvents
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      - text: Pull events from {eventSubscriptionName} on {topicName}, waiting at most {maxWaitTime} seconds.
        slots:
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
          maxWaitTime: query.maxWaitTime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/topics/{topicName}/eventsubscriptions/{eventSubscriptionName}:acknowledge'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge received events by lock token
      effect: write
      questions:
      - How do I tell Event Grid that I've finished processing the events I pulled?
      - Does acknowledging events report which lock tokens failed?
      instructions:
      - text: Acknowledge lock tokens {lockTokens} on subscription {eventSubscriptionName} of topic {topicName}.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      - text: Mark the events I processed as done using tokens {lockTokens} on {eventSubscriptionName} in {topicName}.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/topics/{topicName}/eventsubscriptions/{eventSubscriptionName}:release'].post
  update:
    x-apievangelist-phrasing:
      intent: Release events back for redelivery
      effect: write
      questions:
      - Can I hand pulled events back to the subscription so they get redelivered later?
      - Is it possible to delay redelivery when releasing events I couldn't handle?
      instructions:
      - text: Release lock tokens {lockTokens} on subscription {eventSubscriptionName} of topic {topicName} for redelivery.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      - text: Release events {lockTokens} from {eventSubscriptionName} on {topicName} with a {releaseDelayInSeconds} second delay.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
          releaseDelayInSeconds: query.releaseDelayInSeconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/topics/{topicName}/eventsubscriptions/{eventSubscriptionName}:reject'].post
  update:
    x-apievangelist-phrasing:
      intent: Reject events that cannot be processed
      effect: write
      questions:
      - What should I do with pulled events that are malformed and can never be processed?
      - Can I reject a batch of events so they are not delivered to my consumer again?
      instructions:
      - text: Reject lock tokens {lockTokens} on subscription {eventSubscriptionName} of topic {topicName}.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      - text: Reject the poison events {lockTokens} received from {eventSubscriptionName} on {topicName}.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/topics/{topicName}/eventsubscriptions/{eventSubscriptionName}:renewLock'].post
  update:
    x-apievangelist-phrasing:
      intent: Renew locks on events still being processed
      effect: write
      questions:
      - My event handler is slow — can I extend the lock so the events aren't redelivered mid-processing?
      - How can I renew the lock on events I received from a namespace topic subscription?
      instructions:
      - text: Renew locks {lockTokens} on subscription {eventSubscriptionName} of topic {topicName}.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      - text: Extend the processing lock for tokens {lockTokens} from {eventSubscriptionName} on {topicName}.
        slots:
          lockTokens: requestBody.lockTokens
          eventSubscriptionName: path.eventSubscriptionName
          topicName: path.topicName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an Event Grid topic's properties
      effect: read
      questions:
      - What are the current settings of an Event Grid custom topic?
      - Can I check the endpoint and provisioning state of one Event Grid topic?
      instructions:
      - text: Get Event Grid topic {topicName} in resource group {resourceGroupName} of subscription {subscriptionId}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
      - text: Show the properties of Event Grid topic {topicName} in {resourceGroupName}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create an Event Grid topic
      effect: write
      questions:
      - How can I create a new Event Grid custom topic in a resource group?
      - Which region and SKU settings can I choose when creating an Event Grid topic?
      instructions:
      - text: Create Event Grid topic {topicName} in {location} under resource group {resourceGroupName}, subscription {subscriptionId}.
        slots:
          topicName: path.topicName
          location: requestBody.location
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
      - text: Provision a new Event Grid topic {topicName} in {resourceGroupName} with SKU {sku}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
          sku: requestBody.sku
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an Event Grid topic
      effect: destructive
      questions:
      - How do I remove an Event Grid custom topic I no longer use?
      - Can I delete an Event Grid topic from a resource group?
      instructions:
      - text: Delete Event Grid topic {topicName} from resource group {resourceGroupName} in subscription {subscriptionId}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
      - text: Tear down the Event Grid topic {topicName} in {resourceGroupName}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing Event Grid topic
      effect: write
      questions:
      - Can I change the tags or identity on an Event Grid topic that already exists?
      - What properties of an existing Event Grid topic can be patched?
      instructions:
      - text: Update the tags on Event Grid topic {topicName} in {resourceGroupName}, subscription {subscriptionId}, to {tags}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
          tags: requestBody.tags
      - text: Assign managed identity {identity} to existing Event Grid topic {topicName} in {resourceGroupName}.
        slots:
          identity: requestBody.identity
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.EventGrid/topics'].get
  update:
    x-apievangelist-phrasing:
      intent: List Event Grid topics in a subscription
      effect: read
      questions:
      - Which Event Grid topics exist across my whole Azure subscription?
      - Can I filter or cap the list of Event Grid topics in a subscription?
      instructions:
      - text: List all Event Grid topics in subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      - text: Show the first {top} Event Grid topics in subscription {subscriptionId} matching {filter}.
        slots:
          top: query.$top
          subscriptionId: path.subscriptionId
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics'].get
  update:
    x-apievangelist-phrasing:
      intent: List Event Grid topics in a resource group
      effect: read
      questions:
      - What Event Grid topics are in a particular resource group?
      - Can I page through Event Grid topics within one resource group?
      instructions:
      - text: List Event Grid topics in resource group {resourceGroupName} of subscription {subscriptionId}.
        slots:
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
      - text: Show Event Grid topics in {resourceGroupName} whose name matches {filter}.
        slots:
          resourceGroupName: path.resourceGroupName
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}/listKeys'].post
  update:
    x-apievangelist-phrasing:
      intent: Get the access keys for an Event Grid topic
      effect: read
      questions:
      - Where do I find the shared access keys needed to publish to an Event Grid topic?
      - Can I retrieve both publishing keys for a custom topic?
      instructions:
      - text: Get the two access keys for Event Grid topic {topicName} in {resourceGroupName}, subscription {subscriptionId}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
      - text: Show me the publishing keys for topic {topicName} in resource group {resourceGroupName}.
        slots:
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}/regenerateKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate an Event Grid topic access key
      effect: destructive
      questions:
      - How can I rotate a compromised shared access key on an Event Grid topic?
      - Will regenerating key1 or key2 on a topic break publishers still using the old one?
      instructions:
      - text: Regenerate {keyName} on Event Grid topic {topicName} in {resourceGroupName}, subscription {subscriptionId}.
        slots:
          keyName: requestBody.keyName
          topicName: path.topicName
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
      - text: Rotate access key {keyName} for topic {topicName}.
        slots:
          keyName: requestBody.keyName
          topicName: path.topicName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{providerNamespace}/{resourceTypeName}/{resourceName}/providers/Microsoft.EventGrid/eventTypes'].get
  update:
    x-apievangelist-phrasing:
      intent: List event types a resource can emit
      effect: read
      questions:
      - What event types does a given Azure resource publish to Event Grid?
      - Can I see which events a storage account emits before I subscribe to it?
      instructions:
      - text: List Event Grid event types for {resourceName} of type {providerNamespace}/{resourceTypeName} in {resourceGroupName}, subscription {subscriptionId}.
        slots:
          resourceName: path.resourceName
          providerNamespace: path.providerNamespace
          resourceTypeName: path.resourceTypeName
          resourceGroupName: path.resourceGroupName
          subscriptionId: path.subscriptionId
      - text: Show the events resource {resourceName} can raise.
        slots:
          resourceName: path.resourceName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{scope}/providers/Microsoft.EventGrid/extensionTopics/default'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an extension topic for a scope
      effect: read
      questions:
      - What is an Event Grid extension topic and how do I read its properties for a resource?
      - Can I look up the default extension topic attached to a given scope?
      instructions:
      - text: Get the Event Grid extension topic for scope {scope}.
        slots:
          scope: path.scope
      - text: Show the default extension topic properties at {scope}.
        slots:
          scope: path.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServiceBus/namespaces/{namespaceName}/topics'].get
  update:
    x-apievangelist-phrasing:
      intent: List topics in a Service Bus namespace
      effect: read
      questions:
      - Which topics are defined in my Service Bus namespace?
      - Can I get every Service Bus topic in one namespace at once?
      instructions:
      - text: List all topics in Service Bus namespace {namespaceName}.
        slots:
          namespaceName: path.namespaceName
      - text: Show the Service Bus topics in this namespace.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServiceBus/namespaces/{namespaceName}/topics/{topicName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Service Bus topic
      effect: read
      questions:
      - How can I read the description and settings of one Service Bus topic?
      - Can I check a single Service Bus topic's properties in a namespace?
      instructions:
      - text: Get the description of Service Bus topic {topicName} in namespace {namespaceName}.
        slots:
          topicName: path.topicName
          namespaceName: path.namespaceName
      - text: Show me the settings of Service Bus topic {topicName}.
        slots:
          topicName: path.topicName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServiceBus/namespaces/{namespaceName}/topics/{topicName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a Service Bus topic
      effect: write
      questions:
      - How do I add a new topic to a Service Bus namespace?
      - Can I set topic properties when creating it in Service Bus?
      instructions:
      - text: Create Service Bus topic {topicName} in namespace {namespaceName} with properties {properties}.
        slots:
          topicName: path.topicName
          namespaceName: path.namespaceName
          properties: requestBody.properties
      - text: Add a new topic named {topicName} to the Service Bus namespace.
        slots:
          topicName: path.topicName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ServiceBus/namespaces/{namespaceName}/topics/{topicName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Service Bus topic
      effect: destructive
      questions:
      - Can I remove a topic from a Service Bus namespace?
      - What happens when I delete a Service Bus topic from a resource group?
      instructions:
      - text: Delete Service Bus topic {topicName} from namespace {namespaceName}.
        slots:
          topicName: path.topicName
          namespaceName: path.namespaceName
      - text: Remove the Service Bus topic {topicName} and its namespace entry.
        slots:
          topicName: path.topicName
      method: generated
      generated: '2026-10-01'