# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Asana Tasks API
  version: 1.0.0
extends: openapi/asana-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: 28
- target: $.paths['/tasks/{task_gid}/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tags on a task
      effect: read
      questions:
      - Which tags have been applied to a particular Asana task?
      - Can I see every label attached to one task?
      instructions:
      - text: Show the tags on task {task}.
        slots:
          task: path.task_gid
      - text: List the labels attached to task {task}.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List tasks filtered by project, assignee or section
      effect: read
      questions:
      - How do I list tasks assigned to someone in a workspace?
      - Can I fetch only tasks modified since a certain date?
      - What filter do I need when pulling a filtered set of tasks without a project?
      instructions:
      - text: List tasks assigned to {assignee} in workspace {workspace}.
        slots:
          assignee: query.assignee
          workspace: query.workspace
      - text: Get the tasks in project {project} that are incomplete or completed since {completed_since}.
        slots:
          project: query.project
          completed_since: query.completed_since
      - text: Pull tasks changed since {modified_since} in section {section}.
        slots:
          modified_since: query.modified_since
          section: query.section
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new task
      effect: write
      questions:
      - How do I create a new task in Asana?
      - Can I set the assignee, due date and project when I add a task?
      instructions:
      - text: Create a task called {task} in my workspace.
        slots:
          task: requestBody.data
      - text: 'Add a new to-do with these details: {fields}.'
        slots:
          fields: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the full details of a task
      effect: read
      questions:
      - What does the full record of one task include?
      - Can I look up a task's notes, assignee and due date by its ID?
      instructions:
      - text: Show me the details of task {task}.
        slots:
          task: path.task_gid
      - text: Fetch the complete record for task {task}.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a task's fields
      effect: write
      questions:
      - How can I change the due date or assignee on an existing task?
      - Can I mark a task complete through the API?
      instructions:
      - text: Mark task {task} as complete.
        slots:
          task: path.task_gid
      - text: 'Change task {task} with these updates: {changes}.'
        slots:
          task: path.task_gid
          changes: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a task
      effect: destructive
      questions:
      - What happens to a task after I delete it — can it be recovered from trash?
      - Can I remove a task I no longer need?
      instructions:
      - text: Delete task {task}.
        slots:
          task: path.task_gid
      - text: Move task {task} to the trash.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/duplicate'].post
  update:
    x-apievangelist-phrasing:
      intent: Duplicate a task
      effect: write
      questions:
      - Can I copy an existing task, including its subtasks and attachments?
      - Is duplicating a task done as a background job?
      instructions:
      - text: Duplicate task {task} with the name {settings}.
        slots:
          task: path.task_gid
          settings: requestBody.data
      - text: Make a copy of task {task}.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/projects/{project_gid}/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tasks in a project
      effect: read
      questions:
      - How do I list every task in a project in priority order?
      - Can I limit a project's task list to tasks not yet done?
      instructions:
      - text: List the tasks in project {project}.
        slots:
          project: path.project_gid
      - text: Show tasks in project {project} completed since {since} or still open.
        slots:
          project: path.project_gid
          since: query.completed_since
      method: generated
      generated: '2026-10-01'
- target: $.paths['/sections/{section_gid}/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tasks in a board section
      effect: read
      questions:
      - Which tasks sit in a particular column of my board?
      - Can I list only the cards in one board section?
      instructions:
      - text: List the tasks in section {section}.
        slots:
          section: path.section_gid
      - text: Show open tasks in board column {section} completed since {since}.
        slots:
          section: path.section_gid
          since: query.completed_since
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tags/{tag_gid}/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List tasks that have a tag
      effect: read
      questions:
      - Which tasks carry a specific tag?
      - Can I find everything labeled with one tag?
      instructions:
      - text: List the tasks tagged {tag}.
        slots:
          tag: path.tag_gid
      - text: Show every task that has tag {tag} applied.
        slots:
          tag: path.tag_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user_task_lists/{user_task_list_gid}/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List the tasks in someone's My Tasks
      effect: read
      questions:
      - What tasks are on a user's My Tasks list?
      - Can I pull only incomplete items from someone's My Tasks?
      instructions:
      - text: List the tasks in user task list {list}.
        slots:
          list: path.user_task_list_gid
      - text: Show My Tasks items from list {list} that are open or completed since {since}.
        slots:
          list: path.user_task_list_gid
          since: query.completed_since
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/subtasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a task's subtasks
      effect: read
      questions:
      - How do I see the subtasks under a task?
      - Can I get the child tasks broken out of a parent task?
      instructions:
      - text: List the subtasks of task {task}.
        slots:
          task: path.task_gid
      - text: Show the child tasks under task {task}.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/subtasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a subtask under a task
      effect: write
      questions:
      - How do I add a subtask to an existing task?
      - Can I break a task into smaller subtasks via the API?
      instructions:
      - text: Add a subtask named {subtask} under task {task}.
        slots:
          task: path.task_gid
          subtask: requestBody.data
      - text: 'Create a child task beneath task {task} with these details: {fields}.'
        slots:
          task: path.task_gid
          fields: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/setParent'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a task's parent task
      effect: write
      questions:
      - Can I turn a standalone task into a subtask of another task?
      - Is there a way to move a subtask to a different parent or remove its parent?
      instructions:
      - text: Make task {task} a subtask of {parent}.
        slots:
          task: path.task_gid
          parent: requestBody.data
      - text: Detach task {task} from its parent so it has no parent task.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/dependencies'].get
  update:
    x-apievangelist-phrasing:
      intent: List what a task is waiting on
      effect: read
      questions:
      - Which tasks must be finished before this one can start?
      - Can I see the dependencies blocking a task?
      instructions:
      - text: List the dependencies of task {task}.
        slots:
          task: path.task_gid
      - text: Show which tasks task {task} is blocked by.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/addDependencies'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark tasks as blockers of a task
      effect: write
      questions:
      - How do I say a task can't start until other tasks are done?
      - Is there a cap on how many dependencies and dependents a task can have?
      instructions:
      - text: Make task {task} depend on tasks {dependencies}.
        slots:
          task: path.task_gid
          dependencies: requestBody.data
      - text: Mark {dependencies} as blocking task {task}.
        slots:
          task: path.task_gid
          dependencies: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/removeDependencies'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink blocking tasks from a task
      effect: write
      questions:
      - Can I remove a blocker from a task's dependencies?
      - How do I stop a task from waiting on another task?
      instructions:
      - text: Unlink dependencies {dependencies} from task {task}.
        slots:
          task: path.task_gid
          dependencies: requestBody.data
      - text: Remove the blockers {dependencies} on task {task}.
        slots:
          task: path.task_gid
          dependencies: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/dependents'].get
  update:
    x-apievangelist-phrasing:
      intent: List tasks waiting on a task
      effect: read
      questions:
      - Which tasks are blocked until this task is done?
      - Can I see the downstream dependents of a task?
      instructions:
      - text: List the dependents of task {task}.
        slots:
          task: path.task_gid
      - text: Show which tasks are waiting on task {task}.
        slots:
          task: path.task_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/addDependents'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark tasks as waiting on a task
      effect: write
      questions:
      - How do I make other tasks wait on this one?
      - Can I add several downstream dependents to a task at once?
      instructions:
      - text: Make tasks {dependents} dependents of task {task}.
        slots:
          task: path.task_gid
          dependents: requestBody.data
      - text: Set {dependents} to wait until task {task} is finished.
        slots:
          task: path.task_gid
          dependents: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/removeDependents'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink waiting tasks from a task
      effect: write
      questions:
      - Can I remove a dependent task so it no longer waits on this one?
      - How do I unlink downstream tasks from a blocker?
      instructions:
      - text: Unlink dependents {dependents} from task {task}.
        slots:
          task: path.task_gid
          dependents: requestBody.data
      - text: Stop tasks {dependents} from waiting on task {task}.
        slots:
          task: path.task_gid
          dependents: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/addProject'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a task to a project
      effect: write
      questions:
      - Can one task live in more than one project?
      - How do I put an existing task into a project at a specific position or section?
      instructions:
      - text: Add task {task} to project {project}.
        slots:
          task: path.task_gid
          project: requestBody.data
      - text: Put task {task} into another project with placement {placement}.
        slots:
          task: path.task_gid
          placement: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/removeProject'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a task from a project
      effect: write
      questions:
      - Does removing a task from a project delete the task?
      - How do I take a task out of one of its projects?
      instructions:
      - text: Remove task {task} from project {project}.
        slots:
          task: path.task_gid
          project: requestBody.data
      - text: Take task {task} out of project {project} but keep the task.
        slots:
          task: path.task_gid
          project: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/addTag'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a tag to a task
      effect: write
      questions:
      - How do I tag a task?
      - Can I apply an existing tag to a task?
      instructions:
      - text: Add tag {tag} to task {task}.
        slots:
          task: path.task_gid
          tag: requestBody.data
      - text: Label task {task} with tag {tag}.
        slots:
          task: path.task_gid
          tag: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/removeTag'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove a tag from a task
      effect: write
      questions:
      - Can I take a tag off a task without deleting the tag?
      - What's the way to untag a single task?
      instructions:
      - text: Remove tag {tag} from task {task}.
        slots:
          task: path.task_gid
          tag: requestBody.data
      - text: Untag task {task} by removing {tag}.
        slots:
          task: path.task_gid
          tag: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/addFollowers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add followers to a task
      effect: write
      questions:
      - How do I add collaborators who get notified about a task?
      - Can I add several followers to a task in one call?
      instructions:
      - text: Add followers {followers} to task {task}.
        slots:
          task: path.task_gid
          followers: requestBody.data
      - text: Subscribe {followers} to updates on task {task}.
        slots:
          task: path.task_gid
          followers: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/tasks/{task_gid}/removeFollowers'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove followers from a task
      effect: write
      questions:
      - Can I stop someone from following a task?
      - What's returned after followers are taken off a task?
      instructions:
      - text: Remove followers {followers} from task {task}.
        slots:
          task: path.task_gid
          followers: requestBody.data
      - text: Unsubscribe {followers} from task {task}.
        slots:
          task: path.task_gid
          followers: requestBody.data
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace_gid}/tasks/custom_id/{custom_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a task by its custom ID
      effect: read
      questions:
      - Can I find a task using its custom ID shortcode instead of its gid?
      - How do I resolve a ticket-style custom ID to the actual task?
      instructions:
      - text: Find the task with custom ID {custom_id} in workspace {workspace}.
        slots:
          custom_id: path.custom_id
          workspace: path.workspace_gid
      - text: Look up task {custom_id} by its shortcode in workspace {workspace}.
        slots:
          custom_id: path.custom_id
          workspace: path.workspace_gid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/workspaces/{workspace_gid}/tasks/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search tasks in a workspace with advanced filters
      effect: read
      questions:
      - Can I search tasks by text, due date range and assignee like advanced search in the app?
      - Which tasks in my workspace are blocked or overdue?
      - Is it possible to sort task search results by due date or modification time?
      instructions:
      - text: Search workspace {workspace} for tasks matching {text}.
        slots:
          workspace: path.workspace_gid
          text: query.text
      - text: Find incomplete tasks in workspace {workspace} due before {due_before}.
        slots:
          workspace: path.workspace_gid
          due_before: query.due_on.before
      - text: Search workspace {workspace} for tasks in projects {projects} that have attachments.
        slots:
          workspace: path.workspace_gid
          projects: query.projects.any
      method: generated
      generated: '2026-10-01'