# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Live Direct Marketing Online Briefs API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-briefs-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: 27
- target: $.paths['/api/briefs/schemas'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the available brief JSON schemas
      effect: read
      questions:
      - What JSON schemas can a brief's content follow?
      - Which brief schema versions are available in my workspace?
      instructions:
      - text: Show me the available brief JSON schemas.
      - text: Fetch the brief schemas for tenant {tenant}.
        slots:
          tenant: header.X-Tenant-Id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/intake'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the intake email address for a brief
      effect: read
      questions:
      - What email address do I forward material to so it lands on a specific brief?
      - Is there a workspace intake address to use before any brief exists?
      instructions:
      - text: Get the intake address for brief {briefId} in {language}.
        slots:
          briefId: query.briefId
          language: header.accept-language
      - text: Look up the intake address for the brief at URL {briefUrl}, language {language}.
        slots:
          briefUrl: query.briefUrl
          language: header.accept-language
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/intake/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List incoming intake messages
      effect: read
      questions:
      - Which messages have arrived in the brief intake inbox?
      - Can I filter intake messages by sender or by the date they were received?
      - How do I see only intake items still waiting for review?
      instructions:
      - text: List intake messages with status {status}.
        slots:
          status: query.status
      - text: Show intake items from sender {sender} received after {receivedFrom}.
        slots:
          sender: query.sender
          receivedFrom: query.receivedFrom
      - text: List intake messages attached to brief {briefId}.
        slots:
          briefId: query.briefId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/intake/items/{itemId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one intake item with its provenance
      effect: read
      questions:
      - Can I see the full original intake message with its attachments and work log?
      - Where did a particular intake item come from?
      instructions:
      - text: Open intake item {itemId} with its attachments and work log.
        slots:
          itemId: path.itemId
      - text: Show the provenance of intake item {itemId}.
        slots:
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/intake/items/{itemId}/status'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change an intake item's review status
      effect: write
      questions:
      - How do I mark an intake message as ignored or rejected?
      - Do I have to give a reason when moving an intake item into review?
      instructions:
      - text: Set intake item {itemId} to {status} because {reason}, idempotency key {key}.
        slots:
          itemId: path.itemId
          status: requestBody.status
          reason: requestBody.reason
          key: requestBody.idempotencyKey
      - text: Reject intake item {itemId} with reason {reason} using key {key}.
        slots:
          itemId: path.itemId
          reason: requestBody.reason
          key: requestBody.idempotencyKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/intake/items/{itemId}/link'].post
  update:
    x-apievangelist-phrasing:
      intent: Link an intake item to a brief
      effect: write
      questions:
      - How do I attach an incoming intake message and its files to a brief?
      - Can I also tie the intake item to a contact or company when linking it?
      instructions:
      - text: Link intake item {itemId} to brief {briefId} because {reason}, key {key}.
        slots:
          itemId: path.itemId
          briefId: requestBody.briefId
          reason: requestBody.reason
          key: requestBody.idempotencyKey
      - text: Attach intake item {itemId} to brief {briefId} and company {companyId}, reason {reason}, key {key}.
        slots:
          itemId: path.itemId
          briefId: requestBody.briefId
          companyId: requestBody.companyId
          reason: requestBody.reason
          key: requestBody.idempotencyKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/intake/items/{itemId}/log'].post
  update:
    x-apievangelist-phrasing:
      intent: Log agent work on an intake item
      effect: write
      questions:
      - How does an agent record what it did with an intake message?
      - Can I append a work-log entry to an intake item with source references?
      instructions:
      - text: Log action {action} on intake item {itemId} with reason {reason}, key {key}.
        slots:
          action: requestBody.action
          itemId: path.itemId
          reason: requestBody.reason
          key: requestBody.idempotencyKey
      - text: 'Append a work-log event {action} to intake item {itemId} for brief {briefId}: {reason} (key {key}).'
        slots:
          action: requestBody.action
          itemId: path.itemId
          briefId: requestBody.briefId
          reason: requestBody.reason
          key: requestBody.idempotencyKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs'].get
  update:
    x-apievangelist-phrasing:
      intent: List briefs
      effect: read
      questions:
      - Which campaign briefs exist in my workspace?
      - Can I search briefs by name and include deleted ones?
      instructions:
      - text: List my active briefs.
      - text: Search briefs for {search}, including deleted ones.
        slots:
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a brief
      effect: write
      questions:
      - How do I start a new brief for an outreach campaign?
      - Can a new brief target a specific company list from the start?
      instructions:
      - text: Create a brief named {name}.
        slots:
          name: requestBody.name
      - text: Create brief {name} described as {description} targeting company list {listId}.
        slots:
          name: requestBody.name
          description: requestBody.description
          listId: requestBody.targetCompanyListId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/attachments/content'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the content of a brief attachment
      effect: read
      questions:
      - Can I read the text inside a file attached to a brief?
      - How do I page through a long brief attachment or pull out one of its images?
      instructions:
      - text: Read attachment {attachmentRef} of brief {id}.
        slots:
          attachmentRef: query.attachmentRef
          id: path.id
      - text: Get image {imageRef} from attachment {attachmentRef} on brief {id}.
        slots:
          imageRef: query.imageRef
          attachmentRef: query.attachmentRef
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brief
      effect: read
      questions:
      - What's in a particular brief right now?
      - Can I fetch one brief's full details by its id?
      instructions:
      - text: Show brief {id}.
        slots:
          id: path.id
      - text: Fetch the details of brief {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Move a brief to trash
      effect: destructive
      questions:
      - How do I delete a brief I no longer need?
      - Do I need to give a reason when deleting a brief?
      instructions:
      - text: Delete brief {id} with reason {reason}.
        slots:
          id: path.id
          reason: query.reason
      - text: Trash brief {id} because {reason}.
        slots:
          id: path.id
          reason: query.reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or re-describe a brief
      effect: write
      questions:
      - How do I rename a brief or change its description?
      - Can I deactivate a brief or point it at a different company list?
      instructions:
      - text: Rename brief {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Change brief {id}'s target company list to {listId}.
        slots:
          id: path.id
          listId: requestBody.targetCompanyListId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/content'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch the content body of a brief
      effect: write
      questions:
      - How do I edit the personas or examples inside a brief's content?
      - What happens if I try to change a locked section of a brief's content?
      instructions:
      - text: Apply content patch {patch} to brief {id}.
        slots:
          patch: requestBody.patch
          id: path.id
      - text: Merge {patch} into the content of brief {id} with reason {reason}.
        slots:
          patch: requestBody.patch
          id: path.id
          reason: requestBody.reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/variables'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a brief's template variables
      effect: write
      questions:
      - How do I change the template variables a brief fills into its copy?
      - Can I patch just a few brief variables without rewriting them all?
      instructions:
      - text: Patch the template variables of brief {id} with {patch}.
        slots:
          id: path.id
          patch: requestBody.patch
      - text: Set brief {id}'s variables to {patch} because {reason}.
        slots:
          id: path.id
          patch: requestBody.patch
          reason: requestBody.reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/locks'].patch
  update:
    x-apievangelist-phrasing:
      intent: Lock or unlock sections of a brief
      effect: write
      questions:
      - How do I lock a section of a brief so it can't be edited?
      - Can I unlock brief sections that were previously locked?
      instructions:
      - text: Update the section locks on brief {id}.
        slots:
          id: path.id
      - text: Change which sections are locked in brief {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a deleted brief
      effect: write
      questions:
      - Can I bring back a brief I deleted by mistake?
      - How do I undo a brief deletion?
      instructions:
      - text: Restore deleted brief {id}.
        slots:
          id: path.id
      - text: Undelete brief {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/copy'].post
  update:
    x-apievangelist-phrasing:
      intent: Duplicate a brief
      effect: write
      questions:
      - Can I make a copy of an existing brief to start a similar campaign?
      - How do I clone a brief?
      instructions:
      - text: Duplicate brief {id}.
        slots:
          id: path.id
      - text: Make a copy of brief {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/audit'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a brief's change history
      effect: read
      questions:
      - Who changed a brief and when?
      - Is there an audit trail of edits made to a brief?
      instructions:
      - text: Show the last {limit} audit entries for brief {id}.
        slots:
          limit: query.limit
          id: path.id
      - text: List the change history of brief {id}, up to {limit} entries.
        slots:
          id: path.id
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/mail'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a brief's intake mailbox and mail feed
      effect: read
      questions:
      - Which emails have been received into a brief's mailbox?
      - Can I see a brief's intake address together with the mail it has collected?
      instructions:
      - text: Show the mail feed for brief {id} in {language}.
        slots:
          id: path.id
          language: header.accept-language
      - text: List the latest {limit} emails received by brief {id}, language {language}.
        slots:
          limit: query.limit
          id: path.id
          language: header.accept-language
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/mail/attachments/{attachmentId}/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an attachment from a brief's mail
      effect: read
      questions:
      - How do I download a file that was emailed into a brief?
      - Can I fetch an attachment from a brief's mail feed?
      instructions:
      - text: Download attachment {attachmentId} from brief {id}'s mail.
        slots:
          attachmentId: path.attachmentId
          id: path.id
      - text: Save mail attachment {attachmentId} of brief {id}.
        slots:
          attachmentId: path.attachmentId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/intake-alias'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a brief's intake email alias
      effect: write
      questions:
      - Can I give a brief's intake address a friendlier name?
      - How do I change the readable alias of a brief's intake email?
      instructions:
      - text: Change the intake alias of brief {id} to {alias} (locale {locale}, language {language}).
        slots:
          id: path.id
          alias: requestBody.alias
          locale: query.locale
          language: header.accept-language
      - text: Rename brief {id}'s intake address alias to {alias}, locale {locale}, language {language}.
        slots:
          id: path.id
          alias: requestBody.alias
          locale: query.locale
          language: header.accept-language
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{id}/expert'].get
  update:
    x-apievangelist-phrasing:
      intent: Run the SDR expert review on a brief
      effect: read
      questions:
      - What gaps does the SDR expert find in my brief and what does it recommend?
      - Can I get the brief expert's recommendations alongside the live schema?
      instructions:
      - text: Run the SDR expert flow on brief {id} in {language}.
        slots:
          id: path.id
          language: header.accept-language
      - text: Get expert {include} for brief {id}, language {language}.
        slots:
          include: query.include
          id: path.id
          language: header.accept-language
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{briefId}/memory'].get
  update:
    x-apievangelist-phrasing:
      intent: List a brief's memory entries
      effect: read
      questions:
      - What decisions and open questions have been recorded against a brief?
      - Can I see rejected proposals in a brief's memory, not just active entries?
      instructions:
      - text: List the active memory entries for brief {briefId}.
        slots:
          briefId: path.briefId
      - text: Show {kind} memory entries on brief {briefId} across all statuses.
        slots:
          kind: query.kind
          briefId: path.briefId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{briefId}/memory'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a decision or note in a brief's memory
      effect: write
      questions:
      - How do I record a decision or open question on a brief so later agents see it?
      - Can I log a rejected proposal with the reason so it isn't suggested again?
      instructions:
      - text: Record a memory entry on brief {briefId}.
        slots:
          briefId: path.briefId
      - text: Add a rejected-proposal note to brief {briefId}'s memory.
        slots:
          briefId: path.briefId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{briefId}/memory/{entryId}/resolve'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve a brief memory entry
      effect: write
      questions:
      - How do I close out an open question in a brief's memory?
      - Can I stop a memory entry from being sent to the brief expert?
      instructions:
      - text: Mark memory entry {entryId} on brief {briefId} as resolved.
        slots:
          entryId: path.entryId
          briefId: path.briefId
      - text: Resolve entry {entryId} in brief {briefId}'s memory.
        slots:
          entryId: path.entryId
          briefId: path.briefId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/briefs/{briefId}/memory/migrate-content-review'].post
  update:
    x-apievangelist-phrasing:
      intent: Migrate a brief's review block into memory
      effect: write
      questions:
      - How do I move the old content review notes on a brief into memory entries?
      - Is it safe to run the content-review migration on a brief more than once?
      instructions:
      - text: Migrate the content review block of brief {briefId} into memory.
        slots:
          briefId: path.briefId
      - text: Convert brief {briefId}'s review notes into memory entries.
        slots:
          briefId: path.briefId
      method: generated
      generated: '2026-10-01'