# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mapp Engage public Async API
  version: 1.0.0
extends: openapi/mapp-async-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: 8
- target: $.paths['/async/getNextIndex'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the next poll index for a topic
      effect: read
      questions:
      - How do I switch from managed polling to polling by my own index?
      - What index should I start from after my last poll of a topic?
      instructions:
      - text: Get the next index for topic {topic}.
        slots:
          topic: query.topic
      - text: Tell me where to resume polling topic {topic} by index.
        slots:
          topic: query.topic
      method: generated
      generated: '2026-09-26'
- target: $.paths['/async/getPollCount'].get
  update:
    x-apievangelist-phrasing:
      intent: Count results already polled for a topic
      effect: read
      questions:
      - How many result items have been retrieved for a topic so far?
      - Can I see the polled count for an async topic?
      instructions:
      - text: Get the poll count for topic {topic}.
        slots:
          topic: query.topic
      - text: Count how many results I've pulled from {topic}.
        slots:
          topic: query.topic
      method: generated
      generated: '2026-09-26'
- target: $.paths['/async/getSubmitCount'].get
  update:
    x-apievangelist-phrasing:
      intent: Count jobs submitted for a topic
      effect: read
      questions:
      - How many async jobs have been submitted for a topic?
      - Can I check the submitted job total for my API script?
      instructions:
      - text: Get the number of submitted jobs for my topic.
      - text: Count job submissions for the async script.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/async/pollByType'].get
  update:
    x-apievangelist-phrasing:
      intent: Poll events by event type
      effect: read
      questions:
      - Can I pull link click or read tracking events from the result queue by type?
      - Which event types can I poll, and does allMessages include sentToMta?
      instructions:
      - text: Poll {limit} {type} events.
        slots:
          limit: query.limit
          type: query.type
      - text: Fetch the next 10000 linkClick events of type {type}.
        slots:
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/async/pollByIndex'].get
  update:
    x-apievangelist-phrasing:
      intent: Poll topic results from an index
      effect: read
      questions:
      - Can I read queue results from an offset I manage myself?
      - How do I page through topic results starting at a given index?
      instructions:
      - text: Poll {limit} results from topic {topic} starting at index {index}.
        slots:
          limit: query.limit
          topic: query.topic
          index: query.index
      - text: Re-read topic {topic} from index {index}.
        slots:
          topic: query.topic
          index: query.index
      method: generated
      generated: '2026-09-26'
- target: $.paths['/async/pollByRange'].get
  update:
    x-apievangelist-phrasing:
      intent: Poll events within a time range
      effect: read
      questions:
      - Can I pull events of one type between two timestamps?
      - What's the call to fetch link clicks from a specific window?
      instructions:
      - text: Poll up to {limit} {type} events from {from} to {to}.
        slots:
          limit: query.limit
          type: query.type
          from: query.from
          to: query.to
      - text: Get {type} events between {from} and {to}.
        slots:
          type: query.type
          from: query.from
          to: query.to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/async/poll'].get
  update:
    x-apievangelist-phrasing:
      intent: Poll and consume results for a topic
      effect: read
      questions:
      - Are async results removed from the server once I poll them?
      - How can I read the next batch of results for a topic from the queue?
      instructions:
      - text: Poll {limit} results from topic {topic}.
        slots:
          limit: query.limit
          topic: query.topic
      - text: Pull and consume the next results for {topic}.
        slots:
          topic: query.topic
      method: generated
      generated: '2026-09-26'
- target: $.paths['/async/submit'].get
  update:
    x-apievangelist-phrasing:
      intent: Start an asynchronous API script job
      effect: write
      questions:
      - Can I run one of my custom API scripts asynchronously and collect results later?
      - How does submitting an async job relate to polling results by topic?
      instructions:
      - text: Submit an async job for my API script with these arguments.
      - text: Kick off the export script as an asynchronous job.
      method: generated
      generated: '2026-09-26'