# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Boom Initiatives API
  version: 1.0.0
extends: openapi/boom-ai-initiatives-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: 23
- target: $.paths['/api/v1/initiatives'].get
  update:
    x-apievangelist-phrasing:
      intent: List my initiatives
      effect: read
      questions:
      - Which initiatives does my organization have running right now?
      - Can I list only the active initiatives and leave out the drafts?
      instructions:
      - text: List my initiatives, newest first.
      - text: Show me every initiative with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a draft initiative
      effect: write
      questions:
      - How do I start a new WhatsApp outreach initiative in Boom?
      - What is the minimum I need to create a draft initiative — just a name?
      - Can a new initiative keep enrolling people on a schedule instead of ending after one batch?
      instructions:
      - text: Create a draft initiative called {name}.
        slots:
          name: requestBody.name
      - text: Create a new initiative named {name} whose objective is {objective}, asking {guidingQuestions}.
        slots:
          name: requestBody.name
          objective: requestBody.objective
          guidingQuestions: requestBody.guidingQuestions
      - text: Set up a recurring initiative {name} that makes at most {maxAttempts} outreach attempts per person.
        slots:
          name: requestBody.name
          maxAttempts: requestBody.maxAttempts
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one initiative's details
      effect: read
      questions:
      - What is the current status and objective of a specific initiative?
      - Can I look up one initiative by its id to see how it is configured?
      instructions:
      - text: Show me initiative {id}.
        slots:
          id: path.id
      - text: Pull up the settings of initiative {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a draft initiative
      effect: write
      questions:
      - Can I change the objective or guiding context of an initiative that is still a draft?
      - Why can't I edit an initiative after it has launched?
      - How do I change the bot-disclosure reply on a draft initiative?
      instructions:
      - text: Rename draft initiative {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Change the flag condition on draft initiative {id} to {flagCondition}.
        slots:
          id: path.id
          flagCondition: requestBody.flagCondition
      - text: Update the objective of draft initiative {id} to {objective}.
        slots:
          id: path.id
          objective: requestBody.objective
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive a finished initiative
      effect: write
      questions:
      - How do I hide a completed initiative from my initiatives list?
      - Can I archive an initiative that was canceled?
      instructions:
      - text: Archive initiative {id}.
        slots:
          id: path.id
      - text: Move completed initiative {id} out of the default list by archiving it.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an initiative for good
      effect: destructive
      questions:
      - How do I permanently cancel an initiative and stop all its conversations?
      - Is canceling an initiative reversible, and who is allowed to do it?
      instructions:
      - text: Cancel initiative {id} and stop every conversation it is running.
        slots:
          id: path.id
      - text: Terminate initiative {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/data/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an initiative's data summary
      effect: read
      questions:
      - How many participants does an initiative have, and how well is each captured variable covered?
      - What does the rollup of answers look like across an initiative?
      instructions:
      - text: Summarize the captured data for initiative {id}.
        slots:
          id: path.id
      - text: Give me participant count and per-variable coverage for initiative {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/extraction-schema'].get
  update:
    x-apievangelist-phrasing:
      intent: Read an initiative's extraction schema
      effect: read
      questions:
      - Which typed fields is an initiative currently pulling out of each conversation?
      - Does this initiative have an extraction schema configured at all?
      instructions:
      - text: Show me the extraction schema for initiative {id}.
        slots:
          id: path.id
      - text: Fetch the current extraction fields of initiative {id} so I can edit them.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/extraction-schema'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace an initiative's extraction schema
      effect: write
      questions:
      - How do I define which yes/no, number or choice answers get extracted from conversations?
      - Do I send only the changed fields or the whole extraction schema when replacing it?
      instructions:
      - text: Set the extraction schema of initiative {id} to {schema}.
        slots:
          id: path.id
          schema: requestBody.schema
      - text: Replace initiative {id}'s extraction fields with {schema} and note {notes} on the new version.
        slots:
          id: path.id
          schema: requestBody.schema
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/launch'].post
  update:
    x-apievangelist-phrasing:
      intent: Launch a draft initiative
      effect: write
      questions:
      - What has to be in place before a WhatsApp initiative can go live?
      - Does launching an initiative start messaging people straight away?
      instructions:
      - text: Launch initiative {id} and start outreach.
        slots:
          id: path.id
      - text: Take draft initiative {id} live.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/participants'].get
  update:
    x-apievangelist-phrasing:
      intent: List an initiative's participants
      effect: read
      questions:
      - Who has been enrolled in an initiative and what did Boom capture from each of them?
      - Can I find every run a particular person has had in an initiative, including the live one?
      instructions:
      - text: List the participants of initiative {id}.
        slots:
          id: path.id
      - text: Find the runs for person {personExternalId} in initiative {id}.
        slots:
          id: path.id
          personExternalId: query.personExternalId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/participants'].post
  update:
    x-apievangelist-phrasing:
      intent: Enroll people in a WhatsApp initiative
      effect: write
      questions:
      - How do I add contacts to an active initiative so they get the WhatsApp outreach?
      - Will people on the do-not-contact list be messaged if I add them to an initiative?
      instructions:
      - text: Add {people} to initiative {id} and start messaging them.
        slots:
          id: path.id
          people: requestBody.people
      - text: 'Enroll these contacts in active initiative {id}: {people}.'
        slots:
          id: path.id
          people: requestBody.people
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/participants/{participantId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one participant's status and answers
      effect: read
      questions:
      - What status is a single participant in, and what answers have they given so far?
      - Can I check one person's captured answers without pulling the whole participant list?
      instructions:
      - text: Show participant {participantId} in initiative {id}.
        slots:
          id: path.id
          participantId: path.participantId
      - text: Get the captured answers for participant {participantId} of initiative {id}.
        slots:
          id: path.id
          participantId: path.participantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/participants/{participantId}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a participant's conversation transcript
      effect: read
      questions:
      - Did this person ever reply to us, in any initiative?
      - Where can I read the full WhatsApp back-and-forth with one participant?
      instructions:
      - text: Show me the messages exchanged with participant {participantId} in initiative {id}.
        slots:
          id: path.id
          participantId: path.participantId
      - text: Get everything participant {participantId} of initiative {id} has said to us, using scope {scope}.
        slots:
          id: path.id
          participantId: path.participantId
          scope: query.scope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/participants/{participantId}/steps'].get
  update:
    x-apievangelist-phrasing:
      intent: Trace a participant's journey run steps
      effect: read
      questions:
      - Which journey nodes ran for a participant and what signal did each one emit?
      - Why did a participant's journey run stop or error at a certain node?
      instructions:
      - text: Show the node-by-node run timeline for participant {participantId} in initiative {id}.
        slots:
          id: path.id
          participantId: path.participantId
      - text: List the last {limit} journey steps for participant {participantId} of initiative {id}.
        slots:
          id: path.id
          participantId: path.participantId
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/participants/{participantId}/stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop messaging one participant
      effect: destructive
      questions:
      - How do I stop all messages to one person and close their conversation?
      - If I stop a participant, do I lose their answers and transcript?
      instructions:
      - text: Stop messaging participant {participantId} in initiative {id}.
        slots:
          id: path.id
          participantId: path.participantId
      - text: Close the conversation with participant {participantId} of initiative {id}.
        slots:
          id: path.id
          participantId: path.participantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/pause'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause enrollment into an initiative
      effect: write
      questions:
      - Can I stop new people from being enrolled while ongoing conversations keep going?
      - What happens to people already enrolled when an initiative is paused?
      instructions:
      - text: Pause initiative {id}.
        slots:
          id: path.id
      - text: Stop enrolling new people into initiative {id} for now.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/reextract'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-run extraction over past conversations
      effect: write
      questions:
      - How do I pull answers out of conversations that happened before I wrote the extraction schema?
      - Can I see how many conversations would be re-extracted before spending anything?
      - Why do some conversations produce nothing when re-extracted?
      instructions:
      - text: Re-extract the conversations of initiative {id}.
        slots:
          id: path.id
      - text: Do a dry run of re-extraction on initiative {id} and tell me the counts.
        slots:
          id: path.id
      - text: Re-extract initiative {id} conversations created since {fromDate}.
        slots:
          id: path.id
          fromDate: requestBody.fromDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/resume'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume a paused initiative
      effect: write
      questions:
      - How do I get a paused initiative enrolling people again?
      - Can a paused initiative be restarted?
      instructions:
      - text: Resume initiative {id}.
        slots:
          id: path.id
      - text: Start enrolling people into paused initiative {id} again.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/templates'].get
  update:
    x-apievangelist-phrasing:
      intent: See which templates each outreach round sends
      effect: read
      questions:
      - Which WhatsApp template is linked to each outreach round of an initiative?
      - Is round 1 linked yet, so my initiative can launch?
      instructions:
      - text: Show the round-by-round templates linked to initiative {id}.
        slots:
          id: path.id
      - text: Check which outreach templates initiative {id} will send.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/templates'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a WhatsApp template to an outreach round
      effect: write
      questions:
      - How do I attach an approved WhatsApp template as an initiative's first message?
      - Can I use a different template for the follow-up outreach rounds?
      instructions:
      - text: Link template {templateId} to initiative {id} as its first outreach message.
        slots:
          id: path.id
          templateId: requestBody.templateId
      - text: Use template {templateId} for outreach round {round} of initiative {id}.
        slots:
          id: path.id
          templateId: requestBody.templateId
          round: requestBody.round
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/transcripts'].get
  update:
    x-apievangelist-phrasing:
      intent: Export all conversation transcripts
      effect: read
      questions:
      - How can I export every conversation from an initiative without fetching participants one at a time?
      - What is the most participants' transcripts I can get per page?
      instructions:
      - text: Export all conversation transcripts for initiative {id}.
        slots:
          id: path.id
      - text: Get the next page of transcripts for initiative {id} after cursor {cursor}.
        slots:
          id: path.id
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/initiatives/{id}/unarchive'].post
  update:
    x-apievangelist-phrasing:
      intent: Unarchive an initiative
      effect: write
      questions:
      - How do I bring an archived initiative back into my list?
      - Does unarchiving an initiative change its status?
      instructions:
      - text: Unarchive initiative {id}.
        slots:
          id: path.id
      - text: Restore archived initiative {id} to the default list.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'