# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Azure DevOps Work Items API
  version: 1.0.0
extends: openapi/microsoft-azure-devops-work-items-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: 9
- target: $.paths['/wit/workitems'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several work items by ID
      effect: read
      questions:
      - How do I fetch a batch of work items when I know their IDs?
      - Can I see work items as they were at an earlier date?
      instructions:
      - text: Get work items {ids}.
        slots:
          ids: query.ids
      - text: Get fields {fields} for work items {ids}.
        slots:
          fields: query.fields
          ids: query.ids
      - text: Show work items {ids} as of {asOf}.
        slots:
          ids: query.ids
          asOf: query.asOf
      method: generated
      generated: '2026-09-26'
- target: $.paths['/wit/workitems/{type}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a work item
      effect: write
      questions:
      - How do I file a new bug in Azure Boards?
      - Can I validate a new work item without saving it?
      instructions:
      - text: Create a new {type} work item.
        slots:
          type: path.type
      - text: Create a {type} without sending notifications.
        slots:
          type: path.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/wit/workitems/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a work item
      effect: read
      questions:
      - What is the current state of a work item?
      - Can I see a work item's history at a past point in time?
      instructions:
      - text: Show work item {id}.
        slots:
          id: path.id
      - text: Get work item {id} as it was on {asOf}.
        slots:
          id: path.id
          asOf: query.asOf
      method: generated
      generated: '2026-09-26'
- target: $.paths['/wit/workitems/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a work item
      effect: destructive
      questions:
      - Can a deleted work item be restored from the recycle bin?
      - Is there a way to permanently destroy a work item?
      instructions:
      - text: Delete work item {id}.
        slots:
          id: path.id
      - text: Permanently destroy work item {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/wit/workitems/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a work item
      effect: write
      questions:
      - How do I change a work item's state or assignee?
      - Can I add a link to another work item?
      instructions:
      - text: Update work item {id}.
        slots:
          id: path.id
      - text: Update work item {id} without triggering notifications.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{project}/_apis/wit/workitems/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a work item in a project
      effect: read
      questions:
      - What is the status of a work item in a specific project?
      - Can I choose which fields come back for one work item?
      instructions:
      - text: Get work item {id} in project {project} of organization {organization}.
        slots:
          id: path.id
          project: path.project
          organization: path.organization
      - text: Show fields {select} of work item {id} in {project}.
        slots:
          select: query.$select
          id: path.id
          project: path.project
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{project}/_apis/wit/workitems/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a work item in a project
      effect: write
      questions:
      - How do I change fields or links on a work item?
      - Can I update a work item without emailing followers?
      instructions:
      - text: Update work item {id} in project {project} of organization {organization}.
        slots:
          id: path.id
          project: path.project
          organization: path.organization
      - text: Quietly update work item {id} in {project} with notifications suppressed.
        slots:
          id: path.id
          project: path.project
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{project}/_apis/wit/workitems/${type}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a work item in a project
      effect: write
      questions:
      - How do I create a new task in a specific project?
      - Which field values can I set when creating a work item?
      instructions:
      - text: Create a {type} work item in project {project} of organization {organization}.
        slots:
          type: path.type
          project: path.project
          organization: path.organization
      - text: File a new {type} in {project}.
        slots:
          type: path.type
          project: path.project
      method: generated
      generated: '2026-10-01'
- target: $.paths['/{project}/_apis/wit/workitems'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several work items in a project
      effect: read
      questions:
      - How do I fetch a list of work items by ID from one project?
      - Can I retrieve many work items at once with their relations?
      instructions:
      - text: Get work items {ids} from project {project} of organization {organization}.
        slots:
          ids: query.ids
          project: path.project
          organization: path.organization
      - text: Fetch work items {ids} in {project}.
        slots:
          ids: query.ids
          project: path.project
      method: generated
      generated: '2026-10-01'