# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zendesk Skill Based Routing API
  version: 1.0.0
extends: openapi/zendesk-skill-based-routing-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: 18
- target: $.paths['/api/v2/routing/agents/{user_id}/instance_values'].get
  update:
    x-apievangelist-phrasing:
      intent: List an agent's routing skills
      effect: read
      questions:
      - Which skills are assigned to a particular agent for routing?
      - How can I see the attribute values one agent has in skills-based routing?
      instructions:
      - text: Show the routing skills currently assigned to this agent.
      - text: List the attribute values set on that agent's profile.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/agents/{user_id}/instance_values'].post
  update:
    x-apievangelist-phrasing:
      intent: Set or replace an agent's routing skills
      effect: write
      questions:
      - Does setting skills on an agent replace the ones they already have?
      - How do I give one agent a new set of routing skills?
      instructions:
      - text: Replace this agent's skills with Spanish and Billing.
      - text: Assign routing attribute values to the agent, overwriting any existing ones.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/agents/instance_values'].get
  update:
    x-apievangelist-phrasing:
      intent: Get skills for up to 100 agents
      effect: read
      questions:
      - Can I pull the routing skills for a whole team of agents in one call?
      - What's the maximum number of agents I can fetch skills for at once?
      instructions:
      - text: Get the skills for agents {agent_ids}.
        slots:
          agent_ids: query.filter[agent_ids]
      - text: Show attribute values for agents {agent_ids}, {page_size} per page.
        slots:
          agent_ids: query.filter[agent_ids]
          page_size: query.page[size]
      - text: Fetch the next page of agent skills for {agent_ids} after cursor {after}.
        slots:
          agent_ids: query.filter[agent_ids]
          after: query.page[after]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/agents/instance_values/job'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk add, replace or remove agent skills
      effect: write
      questions:
      - How do I add a skill to 100 agents at once?
      - Can a bulk job remove a routing skill from many agents together?
      instructions:
      - text: Start a job that adds the French skill to every agent on the EMEA team.
      - text: Bulk remove the Legacy Product skill from these agents.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List routing attributes on the account
      effect: read
      questions:
      - What routing attributes, like Language or Product, are defined on our account?
      - Can I sideload attribute values when listing routing attributes?
      instructions:
      - text: List all skills-based routing attributes in the account.
      - text: Show every routing attribute along with its available values.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a routing attribute
      effect: write
      questions:
      - How do I add a new skill category such as Language for routing?
      - Can I create a routing attribute type that skills will belong to?
      instructions:
      - text: Create a routing attribute called Product Line.
      - text: Add a new skill category named Region for skills-based routing.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a routing attribute
      effect: read
      questions:
      - How do I see the details of one routing attribute?
      - What does a single skills-based routing attribute record contain?
      instructions:
      - text: Show the Language routing attribute.
      - text: Get the details of that one routing attribute.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a routing attribute
      effect: write
      questions:
      - Can I rename an existing routing attribute?
      - Who is allowed to update a skills-based routing attribute?
      instructions:
      - text: Rename the Product routing attribute to Product Line.
      - text: Update that routing attribute's name.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a routing attribute
      effect: destructive
      questions:
      - What happens if I delete a whole routing attribute category?
      - Can admins remove a routing attribute we no longer use?
      instructions:
      - text: Delete the Region routing attribute.
      - text: Remove that unused skill category from routing.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}/values'].get
  update:
    x-apievangelist-phrasing:
      intent: List the skills under a routing attribute
      effect: read
      questions:
      - Which skills exist under the Language attribute?
      - How do I see every value defined for one routing attribute?
      instructions:
      - text: List all skills under the Language routing attribute.
      - text: Show the values defined for that attribute.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}/values'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a skill to a routing attribute
      effect: write
      questions:
      - How do I add a new skill like German under the Language attribute?
      - Can I create a skill value inside an existing routing attribute?
      instructions:
      - text: Add a German skill to the Language attribute.
      - text: Create a new value called Enterprise under the Plan routing attribute.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one skill (attribute value)
      effect: read
      questions:
      - How can I inspect a single skill and its settings?
      - What details come back for one attribute value in routing?
      instructions:
      - text: Show the German skill under the Language attribute.
      - text: Get that single attribute value's details.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a skill from an attribute
      effect: destructive
      questions:
      - Can I delete a skill value we've stopped supporting?
      - How do I remove one value from a routing attribute?
      instructions:
      - text: Delete the Portuguese skill from the Language attribute.
      - text: Remove that outdated skill value.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/{attribute_id}/values/{attribute_value_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a skill's name and ticket conditions
      effect: write
      questions:
      - How do I make a skill apply automatically to tickets that meet certain conditions?
      - Can I change the conditions that attach a skill to new tickets?
      instructions:
      - text: Update the Billing skill so it's applied to tickets tagged invoice.
      - text: Rename that skill and change its ticket conditions.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/attributes/definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: List conditions usable to apply skills
      effect: read
      questions:
      - What ticket conditions can I use to automatically apply skills?
      - Which condition definitions are available for routing attributes?
      instructions:
      - text: List the condition definitions available for applying skills to tickets.
      - text: Show which ticket conditions I can use in skill rules.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/requirements/fulfilled'].get
  update:
    x-apievangelist-phrasing:
      intent: Find tickets whose skills match mine
      effect: read
      questions:
      - Which of these tickets match my own skills?
      - Can I check whether I'm qualified for a set of tickets based on routing skills?
      instructions:
      - text: Tell me which of tickets {ticket_ids} match my skills.
        slots:
          ticket_ids: query.ticket_ids
      - text: Check tickets {ticket_ids} against my routing attributes and return the ones I fulfill.
        slots:
          ticket_ids: query.ticket_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/tickets/{ticket_id}/instance_values'].get
  update:
    x-apievangelist-phrasing:
      intent: List the skills required by a ticket
      effect: read
      questions:
      - What skills does a specific ticket require?
      - How do I see which attribute values are attached to a ticket?
      instructions:
      - text: Show the skills attached to this ticket.
      - text: List the routing attribute values on that ticket.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/routing/tickets/{ticket_id}/instance_values'].post
  update:
    x-apievangelist-phrasing:
      intent: Set or replace a ticket's required skills
      effect: write
      questions:
      - How do I set the skills a ticket needs so it routes to the right agent?
      - Are invalid or deleted attributes ignored when I set ticket skills?
      instructions:
      - text: Set this ticket's required skills to Spanish and Payments.
      - text: Replace the skills on that ticket with the Enterprise value.
      method: generated
      generated: '2026-09-26'