API Evangelist conversational phrasing for act.web.api Tasks API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for act.web.api Tasks API
  version: 1.0.0
extends: openapi/act-tasks-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: 37
- target: $.paths['/api/contacts/{contactId}/associated-tasks/{taskId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link a task to a contact
      effect: write
      questions:
      - Can I attach an existing task to a contact in Act!?
      - What happens if the contact is already linked to that task?
      instructions:
      - text: Link task {taskId} to contact {contactId}.
        slots:
          taskId: path.taskId
          contactId: path.contactId
      - text: Add contact {contactId} as a participant on task {taskId}.
        slots:
          taskId: path.taskId
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/associated-tasks/{taskId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a task from a contact
      effect: destructive
      questions:
      - Is there a way to detach a contact from a task without deleting the task itself?
      - Can I take one contact off a shared task?
      instructions:
      - text: Unlink task {taskId} from contact {contactId}.
        slots:
          taskId: path.taskId
          contactId: path.contactId
      - text: Remove contact {contactId} from task {taskId} but keep the task.
        slots:
          taskId: path.taskId
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{taskId}/clear'].put
  update:
    x-apievangelist-phrasing:
      intent: Complete a single task and log history
      effect: write
      questions:
      - How do I mark one task as done and record a history entry for it?
      - Can I record a result when clearing an individual task?
      instructions:
      - text: Clear task {taskId} with result {result}.
        slots:
          taskId: path.taskId
          result: requestBody.result
      - text: Mark task {taskId} as completed.
        slots:
          taskId: path.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{taskId}/clear'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reopen a single cleared task
      effect: destructive
      questions:
      - Can I reopen a task I already marked as cleared?
      - What undoes the completion of one specific task?
      instructions:
      - text: Reopen cleared task {taskId}.
        slots:
          taskId: path.taskId
      - text: Undo the clear on task {taskId} so it is open again.
        slots:
          taskId: path.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/clear'].put
  update:
    x-apievangelist-phrasing:
      intent: Complete several tasks at once
      effect: write
      questions:
      - Is it possible to mark a whole batch of tasks complete in one call?
      - Can multiple cleared tasks share the same result and history entry?
      instructions:
      - text: Clear tasks {tasks} with result {result}.
        slots:
          tasks: requestBody.tasks
          result: requestBody.result
      - text: Mark every task in {tasks} as completed.
        slots:
          tasks: requestBody.tasks
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/clear'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reopen several cleared tasks
      effect: destructive
      questions:
      - Can I un-clear a whole list of completed tasks together?
      - What reopens multiple finished tasks in one request?
      instructions:
      - text: Reopen the cleared tasks {tasks}.
        slots:
          tasks: requestBody.tasks
      - text: Undo completion for each of the tasks {tasks}.
        slots:
          tasks: requestBody.tasks
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/recurring-tasks/{recurringId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a recurring task series
      effect: read
      questions:
      - How can I look up one recurring task series by its ID?
      - What schedule does a particular repeating task follow?
      instructions:
      - text: Show recurring task series {recurringId}.
        slots:
          recurringId: path.recurringId
      - text: Fetch the recurrence details of series {recurringId}.
        slots:
          recurringId: path.recurringId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/recurring-tasks/{recurringId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a recurring task series
      effect: write
      questions:
      - Can I change the recurrence pattern of a repeating task series?
      - Is there a full update that overwrites a recurring task series with new details?
      instructions:
      - text: Update recurring series {recurringId} with subject {subject} and recurrence {recurSpec}.
        slots:
          recurringId: path.recurringId
          subject: requestBody.subject
          recurSpec: requestBody.recurSpec
      - text: Replace recurring task {recurringId} so it starts at {startTime}.
        slots:
          recurringId: path.recurringId
          startTime: requestBody.startTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/recurring-tasks/{recurringId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a recurring task series
      effect: destructive
      questions:
      - If I delete a recurring task series, do occurrences I rescheduled survive?
      - How do I stop a task from repeating altogether?
      instructions:
      - text: Delete recurring task series {recurringId}.
        slots:
          recurringId: path.recurringId
      - text: Remove the whole repeating series {recurringId}.
        slots:
          recurringId: path.recurringId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/recurring-tasks/{recurringId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a recurring task series
      effect: write
      questions:
      - Can I change only the location of a recurring series without resending everything?
      - Which fields of a repeating task series can be patched?
      instructions:
      - text: Change the location of recurring series {recurringId} to {location}.
        slots:
          recurringId: path.recurringId
          location: requestBody.location
      - text: Set the priority of recurring series {recurringId} to {activityPriorityId}.
        slots:
          recurringId: path.recurringId
          activityPriorityId: requestBody.activityPriorityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{taskId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task
      effect: read
      questions:
      - Where do I fetch a single task's details by its ID?
      - Who is a specific task scheduled for and when is it due?
      instructions:
      - text: Show task {taskId}.
        slots:
          taskId: path.taskId
      - text: Get the details of task {taskId}.
        slots:
          taskId: path.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{taskId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a task's details
      effect: write
      questions:
      - How do I fully update an existing task?
      - Does a full task update change its recurrence settings?
      instructions:
      - text: Update task {taskId} with subject {subject} and start time {startTime}.
        slots:
          taskId: path.taskId
          subject: requestBody.subject
          startTime: requestBody.startTime
      - text: Overwrite task {taskId} so it ends at {endTime}.
        slots:
          taskId: path.taskId
          endTime: requestBody.endTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{taskId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a task
      effect: destructive
      questions:
      - What call permanently deletes one task by its ID?
      - Can I remove a single task from the calendar for good?
      instructions:
      - text: Delete task {taskId}.
        slots:
          taskId: path.taskId
      - text: Permanently remove task {taskId}.
        slots:
          taskId: path.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{taskId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a task
      effect: write
      questions:
      - Can I change only the subject of a task?
      - Is there a way to reschedule a task by patching just its start time?
      instructions:
      - text: Change the subject of task {taskId} to {subject}.
        slots:
          taskId: path.taskId
          subject: requestBody.subject
      - text: Move task {taskId} to start at {startTime}.
        slots:
          taskId: path.taskId
          startTime: requestBody.startTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List tasks
      effect: read
      questions:
      - How can I list all tasks, optionally narrowed with an OData query?
      - Which tasks exist across the whole database?
      instructions:
      - text: List all tasks.
      - text: Show every task in the database.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a task
      effect: write
      questions:
      - How do I create a new task in Act!?
      - Can the regular task create call set up a recurring task?
      instructions:
      - text: Create a task called {subject} starting {startTime}.
        slots:
          subject: requestBody.subject
          startTime: requestBody.startTime
      - text: Add a task {subject} linked to contacts {contacts}.
        slots:
          subject: requestBody.subject
          contacts: requestBody.contacts
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several tasks
      effect: destructive
      questions:
      - Can I delete several tasks in one request?
      - What bulk-removes a list of tasks?
      instructions:
      - text: Delete tasks {tasks}.
        slots:
          tasks: requestBody.tasks
      - text: 'Remove all of these tasks: {tasks}.'
        slots:
          tasks: requestBody.tasks
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/associated-tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's tasks
      effect: read
      questions:
      - What tasks are tied to a company?
      - Can I include tasks for the company's contacts, not just the company itself?
      instructions:
      - text: List tasks for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show tasks for company {companyId} with scope {showFor}.
        slots:
          companyId: path.companyId
          showFor: query.showFor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/associated-tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a contact's tasks
      effect: read
      questions:
      - Which tasks are linked to a particular contact?
      - Can I filter a contact's tasks with an OData query?
      instructions:
      - text: List tasks for contact {contactId}.
        slots:
          contactId: path.contactId
      - text: Show the tasks associated with contact {contactId}.
        slots:
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{groupId}/associated-tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's tasks
      effect: read
      questions:
      - What tasks belong to a group?
      - Is there a way to see every task associated with one group?
      instructions:
      - text: List tasks for group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show tasks associated with group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List an opportunity's tasks
      effect: read
      questions:
      - Which tasks are attached to a sales opportunity?
      - Can I pull the follow-up tasks for one deal?
      instructions:
      - text: List tasks for opportunity {opportunityId}.
        slots:
          opportunityId: path.opportunityId
      - text: Show the tasks associated with opportunity {opportunityId}.
        slots:
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/recurring-tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List recurring task series
      effect: read
      questions:
      - How do I list all repeating task series?
      - Can I narrow recurring tasks with a restriction or filter?
      instructions:
      - text: List all recurring task series.
      - text: List recurring tasks filtered by {filterBy}.
        slots:
          filterBy: query.filterBy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/recurring-tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a recurring task series
      effect: write
      questions:
      - How do I set up a task that repeats every week?
      - What field defines the recurrence of a new repeating task?
      instructions:
      - text: Create a recurring task {subject} with recurrence {recurSpec}.
        slots:
          subject: requestBody.subject
          recurSpec: requestBody.recurSpec
      - text: Set up a repeating task {subject} starting {startTime} on pattern {recurSpec}.
        slots:
          subject: requestBody.subject
          startTime: requestBody.startTime
          recurSpec: requestBody.recurSpec
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks-lists'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several tasks by ID
      effect: read
      questions:
      - Can I fetch a specific set of tasks by their IDs in one call?
      - What's the way to batch-retrieve tasks when I already know their IDs?
      instructions:
      - text: Get tasks {taskIds}.
        slots:
          taskIds: query.taskIds
      - text: Fetch the tasks with IDs {taskIds}.
        slots:
          taskIds: query.taskIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/priorities'].get
  update:
    x-apievangelist-phrasing:
      intent: List task priorities
      effect: read
      questions:
      - What priority levels can a task have?
      - Where do I find the valid activity priority IDs?
      instructions:
      - text: List the available task priorities.
      - text: Show me the priority options for tasks.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/organizers/{userId}/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a task on behalf of another user
      effect: write
      questions:
      - Can I create a task scheduled for a different user?
      - Is it possible to put a new task on a colleague's calendar for them?
      instructions:
      - text: Create a task {subject} on behalf of user {userId}.
        slots:
          subject: requestBody.subject
          userId: path.userId
      - text: Schedule a task for user {userId} starting {startTime}.
        slots:
          userId: path.userId
          startTime: requestBody.startTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/alarms'].get
  update:
    x-apievangelist-phrasing:
      intent: List my alarmed tasks
      effect: read
      questions:
      - Which of my tasks currently have alarms going off?
      - Where can I see active reminders for the logged-in user?
      instructions:
      - text: Show my current task alarms.
      - text: List the tasks that are alarming for me right now.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/alarms/updates'].get
  update:
    x-apievangelist-phrasing:
      intent: Check alarm state for tracked activities
      effect: read
      questions:
      - How do I find out which tracked activities are no longer alarmed?
      - Can I poll the alarm status for a set of activity IDs?
      instructions:
      - text: Check the alarm state of activities {activityIds}.
        slots:
          activityIds: query.activityIds
      - text: Refresh alarm status for {activityIds}.
        slots:
          activityIds: query.activityIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/alarms/snooze'].put
  update:
    x-apievangelist-phrasing:
      intent: Snooze task alarms
      effect: write
      questions:
      - How do I snooze task reminders?
      - Can I choose how many minutes an alarm is snoozed for?
      instructions:
      - text: Snooze alarms for {activityIds} by {snoozeMinutes} minutes.
        slots:
          activityIds: requestBody.activityIds
          snoozeMinutes: requestBody.snoozeMinutes
      - text: Snooze the reminders on activities {activityIds}.
        slots:
          activityIds: requestBody.activityIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/alarms/mark-snooze-read'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark specific snoozed alarms as read
      effect: write
      questions:
      - Can I mark snoozed alarms as read for certain activities only?
      - Is there a way to acknowledge specific snoozes without clearing them?
      instructions:
      - text: Mark the snoozes on {activityIds} as read.
        slots:
          activityIds: requestBody.activityIds
      - text: Acknowledge snoozed alarms for activities {activityIds}.
        slots:
          activityIds: requestBody.activityIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/alarms/mark-all-snooze-read'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark all my snoozed alarms as read
      effect: write
      questions:
      - Is there a way to mark every one of my snoozed alarms as read?
      - Can I acknowledge all my active snoozes in one go?
      instructions:
      - text: Mark all my snoozed alarms as read.
      - text: Acknowledge every active snooze I have.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/clear-alarms'].put
  update:
    x-apievangelist-phrasing:
      intent: Clear alarms on selected activities
      effect: write
      questions:
      - How do I dismiss alarms on several activities at once?
      - Can I clear reminders for a chosen list of tasks?
      instructions:
      - text: Clear alarms for activities {ids}.
        slots:
          ids: requestBody.ids
      - text: Dismiss the reminders on {ids}.
        slots:
          ids: requestBody.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/clear-all-alarms'].put
  update:
    x-apievangelist-phrasing:
      intent: Clear all of my task alarms
      effect: write
      questions:
      - What dismisses all of my task alarms at once?
      - Can I clear every reminder for the current user?
      instructions:
      - text: Clear all my task alarms.
      - text: Dismiss every alarm I have.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/clear-alarms'].put
  update:
    x-apievangelist-phrasing:
      intent: Clear the alarm on one task
      effect: write
      questions:
      - Can I clear the alarm on just one occurrence of a recurring task?
      - Will clearing by a task's plain GUID dismiss the alarm on every occurrence?
      instructions:
      - text: Clear the alarm on task {id}.
        slots:
          id: path.id
      - text: Dismiss the reminder for occurrence {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{taskId}/duplicate'].put
  update:
    x-apievangelist-phrasing:
      intent: Duplicate a task
      effect: write
      questions:
      - How do I make a copy of an existing task?
      - Can I duplicate one task by its ID?
      instructions:
      - text: Duplicate task {taskId}.
        slots:
          taskId: path.taskId
      - text: Make a copy of task {taskId}.
        slots:
          taskId: path.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/duplicate'].put
  update:
    x-apievangelist-phrasing:
      intent: Duplicate several tasks
      effect: write
      questions:
      - Can I copy several tasks in one request?
      - What bulk-duplicates a list of tasks?
      instructions:
      - text: Duplicate tasks {tasks}.
        slots:
          tasks: requestBody.tasks
      - text: 'Copy each of these tasks: {tasks}.'
        slots:
          tasks: requestBody.tasks
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/organizers/{userId}/tasks/{taskId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a task on behalf of another user
      effect: write
      questions:
      - Can I modify a task that sits on another user's schedule?
      - Is there a way to update a colleague's task on their behalf?
      instructions:
      - text: Update task {taskId} on behalf of user {userId}.
        slots:
          taskId: path.taskId
          userId: path.userId
      - text: Modify user {userId}'s task {taskId}.
        slots:
          taskId: path.taskId
          userId: path.userId
      method: generated
      generated: '2026-10-01'