Deputy · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Deputy V2 Shifts API

38 actions 38 updates phrasing extends openapi/deputy-shifts-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Deputy's API. It is a proposal applied on top of the contract, not a document Deputy publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 38 · first 16 shown; the file carries all of them

$.info
$.paths['/management/v2/shifts'].get
$.paths['/management/v2/shifts'].post
$.paths['/management/v2/shifts/bids:status'].post
$.paths['/management/v2/shifts/copy/job/{jobId}'].get
$.paths['/management/v2/shifts/open/pending-approvals'].post
$.paths['/management/v2/shifts/{id}'].get
$.paths['/management/v2/shifts/{id}'].put
$.paths['/management/v2/shifts/{id}'].delete
$.paths['/management/v2/shifts/{id}/bids:statusCounts'].get
$.paths['/management/v2/shifts/{id}/history'].get
$.paths['/management/v2/shifts/{id}/log'].get
$.paths['/management/v2/shifts/{id}/open:deleteInvitations'].post
$.paths['/management/v2/shifts/{id}/open:invitations'].get
$.paths['/management/v2/shifts/{id}/open:status'].post
$.paths['/management/v2/shifts/{id}/open:statusCounts'].get

OpenAPI Overlay

Raw ↑
# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Deputy V2 Shifts API
  version: 1.0.0
extends: openapi/deputy-shifts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-11-17'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 37
- target: $.paths['/management/v2/shifts'].get
  update:
    x-apievangelist-phrasing:
      intent: List shifts for an employee
      effect: read
      questions:
      - How do I see all shifts assigned to one employee?
      - Can I list shifts for a date range?
      instructions:
      - text: List shifts for employee {employee}.
        slots:
          employee: query.employee
      - text: Show shifts for {employee} between {start} and {end}.
        slots:
          employee: query.employee
          start: query.start
          end: query.end
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shift
      effect: write
      questions:
      - How do I add a new shift for an employee?
      - What fields are required to create a shift?
      instructions:
      - text: Create a shift {shift}.
        slots:
          shift: requestBody.shift
      - text: Add a new shift with override settings {override}.
        slots:
          override: requestBody.override
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/bids:status'].post
  update:
    x-apievangelist-phrasing:
      intent: Decline a shift bid
      effect: write
      questions:
      - How do I decline a shift I was invited to?
      - Can I decline several shift bids at once?
      instructions:
      - text: Decline shift bids {shifts} for employee {employee} with status {status}.
        slots:
          shifts: requestBody.shifts
          employee: requestBody.employee
          status: requestBody.status
      - text: Decline my shift bid {shifts} as {status}.
        slots:
          shifts: requestBody.shifts
          status: requestBody.status
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/copy/job/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a shift copy job
      effect: read
      questions:
      - Has my batch of copied shifts finished?
      - How many shifts failed to copy in a copy job?
      instructions:
      - text: Get the status of copy job {jobId}.
        slots:
          jobId: path.jobId
      - text: Check how many shifts copied in job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/open/pending-approvals'].post
  update:
    x-apievangelist-phrasing:
      intent: List open shifts pending approval
      effect: read
      questions:
      - Which open shifts are waiting for my approval?
      - Can I filter pending approval open shifts by location?
      instructions:
      - text: List open shifts pending approval.
      - text: Show pending approval open shifts at locations {locationIds} between {start} and {end}.
        slots:
          locationIds: requestBody.locationIds
          start: requestBody.start
          end: requestBody.end
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shift
      effect: read
      questions:
      - What are the start and end times of a shift?
      - Can I see one shift's details?
      instructions:
      - text: Get shift {id}.
        slots:
          id: path.id
      - text: Show shift {id} with metadata expanded.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a shift
      effect: write
      questions:
      - How do I change the start time of an existing shift?
      - Can I edit a shift with an override?
      instructions:
      - text: Update shift {id} with {shift}.
        slots:
          id: path.id
          shift: requestBody.shift
      - text: Edit shift {id} using override {override}.
        slots:
          id: path.id
          override: requestBody.override
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shift
      effect: destructive
      questions:
      - How do I remove a shift from the schedule?
      - Can I delete a shift by its ID?
      instructions:
      - text: Delete shift {id}.
        slots:
          id: path.id
      - text: Remove shift {id} from the schedule.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/bids:statusCounts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count bids on a shift
      effect: read
      questions:
      - How many employees have bid on a shift?
      - What does the bid status breakdown look like for a shift?
      instructions:
      - text: Get bid status counts for shift {id}.
        slots:
          id: path.id
      - text: Show how many bids each status has on shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shift's change history
      effect: read
      questions:
      - Who changed a shift and when?
      - Can I see the edit history of a shift?
      instructions:
      - text: Get the history of shift {id}.
        slots:
          id: path.id
      - text: Show who edited shift {id} and when.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/log'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shift's log
      effect: read
      questions:
      - What actions have been logged against a shift?
      - Can I read the shift log?
      instructions:
      - text: Get the log for shift {id}.
        slots:
          id: path.id
      - text: Show the action log on shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/open:deleteInvitations'].post
  update:
    x-apievangelist-phrasing:
      intent: Withdraw open shift invitations
      effect: destructive
      questions:
      - How do I withdraw invitations sent to specific employees on an open shift?
      - Can I revoke open shift invites for certain staff?
      instructions:
      - text: Delete open shift invitations on shift {id} for employees {employees}.
        slots:
          id: path.id
          employees: requestBody.employees
      - text: Withdraw open shift invites on {id} for {employees}.
        slots:
          id: path.id
          employees: requestBody.employees
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/open:invitations'].get
  update:
    x-apievangelist-phrasing:
      intent: List open shift invitations
      effect: read
      questions:
      - Which employees have been invited to an open shift?
      - Can I see the open shift invitation list?
      instructions:
      - text: Get the open shift invitation list for shift {id}.
        slots:
          id: path.id
      - text: Show who was invited to open shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/open:status'].post
  update:
    x-apievangelist-phrasing:
      intent: Accept or decline an open shift
      effect: write
      questions:
      - How do I accept an open shift I was invited to?
      - Can I decline an open shift bid?
      instructions:
      - text: Set the status of open shift {id} to {status}.
        slots:
          id: path.id
          status: requestBody.status
      - text: Accept open shift {id} with status {status}.
        slots:
          id: path.id
          status: requestBody.status
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/open:statusCounts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count open statuses on a shift
      effect: read
      questions:
      - How many open status requests are waiting for a substitute shift?
      - Can I see the status counts for an open shift?
      instructions:
      - text: Get the open status counts for shift {id}.
        slots:
          id: path.id
      - text: Count find-replacement requests on open shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get shift permissions
      effect: read
      questions:
      - What can I offer, swap or cancel on a shift?
      - Can I check the permissions for a shift?
      instructions:
      - text: Get the permissions for shift {id}.
        slots:
          id: path.id
      - text: Show who is allowed to offer, swap or cancel shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}/suggestions'].post
  update:
    x-apievangelist-phrasing:
      intent: Get suggestions for a shift
      effect: read
      questions:
      - Can I get suggestions for a shift?
      - What does the shift suggestion endpoint return?
      instructions:
      - text: Get suggestions for shift {id}.
        slots:
          id: path.id
      - text: Suggest staff for shift {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts/{id}:calculateCost'].post
  update:
    x-apievangelist-phrasing:
      intent: Calculate a shift's cost
      effect: read
      questions:
      - How much would a shift cost with a given list of staff?
      - Can I estimate a shift's potential cost?
      instructions:
      - text: Calculate the potential cost of shift {id} for these staff.
        slots:
          id: path.id
      - text: Estimate the cost of shift {id} for a list of employee IDs.
        slots:
          id: path.id
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:aggregated'].get
  update:
    x-apievangelist-phrasing:
      intent: List shifts aggregated by date
      effect: read
      questions:
      - Can I get shifts grouped by day or week?
      - How do I list shifts for an employee across a date range?
      instructions:
      - text: List shifts for employee {employee} aggregated by {frequency}.
        slots:
          employee: query.employee
          frequency: query.frequency
      - text: Show shifts for {employee} from {start} to {end}.
        slots:
          employee: query.employee
          start: query.start
          end: query.end
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:autobuild'].post
  update:
    x-apievangelist-phrasing:
      intent: Auto-build shifts from history
      effect: write
      questions:
      - How do I generate shifts automatically from past patterns?
      - Can I auto-build shifts for a date range and areas?
      instructions:
      - text: Auto-build shifts for areas {areaIds} from {startDate} to {endDate}.
        slots:
          areaIds: requestBody.areaIds
          startDate: requestBody.startDate
          endDate: requestBody.endDate
      - text: Generate shift templates for {weeksOfHistory} weeks of history.
        slots:
          weeksOfHistory: requestBody.weeksOfHistory
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:autofill'].post
  update:
    x-apievangelist-phrasing:
      intent: Auto-fill open shifts with staff
      effect: write
      questions:
      - Can Deputy automatically staff open shifts using a genetic algorithm?
      - What does autofill optimize for, like cost and workload equality?
      instructions:
      - text: Auto-fill open shifts {shiftIds}.
        slots:
          shiftIds: requestBody.shiftIds
      - text: Optimize staff assignment for shifts {shiftIds} across employees {employeeIds}.
        slots:
          shiftIds: requestBody.shiftIds
          employeeIds: requestBody.employeeIds
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update many shifts at once
      effect: write
      questions:
      - How do I create or update a batch of shifts in one call?
      - Will shifts without an ID be created and ones with an ID updated?
      instructions:
      - text: Bulk upsert shifts {items}.
        slots:
          items: requestBody.items
      - text: 'Upsert shifts {items} and skip counting child shifts: {skipCountChildren}.'
        slots:
          items: requestBody.items
          skipCountChildren: requestBody.skipCountChildren
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:bulkDefaults'].post
  update:
    x-apievangelist-phrasing:
      intent: Get default shift skeletons for dates and areas
      effect: read
      questions:
      - What default shift skeleton would be created for each date and area?
      - Can I get default shifts for a list of dates and areas?
      instructions:
      - text: Get default shift skeletons for dates {dates} and areas {areas}.
        slots:
          dates: requestBody.dates
          areas: requestBody.areas
      - text: Build default shift templates for {dates} in areas {areas}.
        slots:
          dates: requestBody.dates
          areas: requestBody.areas
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:bulkDelete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete many shifts at once
      effect: destructive
      questions:
      - How do I delete a batch of shifts in the background?
      - Can I bypass validation when bulk deleting shifts?
      instructions:
      - text: Bulk delete these shifts.
      - text: Delete the selected shifts in one background job.
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:bulkPatch'].post
  update:
    x-apievangelist-phrasing:
      intent: Partially update many shifts
      effect: write
      questions:
      - Can I change just the employee on a batch of shifts?
      - Which fields can I update on several shifts in one call?
      instructions:
      - text: Patch shifts {data} with fields {patchMask}.
        slots:
          data: requestBody.data
          patchMask: requestBody.patchMask
      - text: Partially update shifts {data} using patch mask {patchMask}.
        slots:
          data: requestBody.data
          patchMask: requestBody.patchMask
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:bulkUpdate'].post
  update:
    x-apievangelist-phrasing:
      intent: Update many shifts with field masks
      effect: write
      questions:
      - Can I update only certain fields on a batch of shifts?
      - Which field masks are supported when bulk updating shifts?
      instructions:
      - text: Bulk update shifts {shifts} with field masks {fieldMasks}.
        slots:
          shifts: requestBody.shifts
          fieldMasks: query.fieldMasks
      - text: Apply field masks {fieldMasks} to shifts {shifts}.
        slots:
          fieldMasks: query.fieldMasks
          shifts: requestBody.shifts
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:copy'].post
  update:
    x-apievangelist-phrasing:
      intent: Copy shifts to new dates
      effect: write
      questions:
      - Can I copy shifts to a range of target dates?
      - Can I copy specific shift IDs to other dates?
      instructions:
      - text: Copy shifts {shiftIds} to target dates {targetDates}.
        slots:
          shiftIds: requestBody.shiftIds
          targetDates: requestBody.targetDates
      - text: Copy shifts {shiftIds} offset by {dayOffsets} days.
        slots:
          shiftIds: requestBody.shiftIds
          dayOffsets: requestBody.dayOffsets
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:defaults'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a default shift skeleton for a date
      effect: read
      questions:
      - What does a default shift look like for a date, start and end time in an area?
      - Can I get a skeleton shift with breaks filled in for one area?
      instructions:
      - text: Get the default shift skeleton for {date} from {start} to {end} in area {area}.
        slots:
          date: requestBody.date
          start: requestBody.start
          end: requestBody.end
          area: requestBody.area
      - text: Build a default shift for {date} in area {area} starting {start}, ending {end}.
        slots:
          date: requestBody.date
          area: requestBody.area
          start: requestBody.start
          end: requestBody.end
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete a shift with compliance override options
      effect: destructive
      questions:
      - How do I delete a shift while passing compliance override settings?
      - Can I skip compliance validation when deleting a single shift?
      - What does the override option do when I remove a shift?
      instructions:
      - text: Delete shift {id} using the delete-with-parameters action.
        slots:
          id: requestBody.id
      - text: Delete shift {id} and apply compliance override settings {override}.
        slots:
          id: requestBody.id
          override: requestBody.override
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:getRosters'].post
  update:
    x-apievangelist-phrasing:
      intent: Get published shift rosters for a period
      effect: read
      questions:
      - Can I get published rosters for a date range?
      - Can I include employee photos and metadata when fetching rosters?
      instructions:
      - text: Get rosters from {start} to {end}.
        slots:
          start: requestBody.start
          end: requestBody.end
      - text: Get rosters for locations {locationIds} from {start} to {end}.
        slots:
          locationIds: requestBody.locationIds
          start: requestBody.start
          end: requestBody.end
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:link'].post
  update:
    x-apievangelist-phrasing:
      intent: Link two shifts together
      effect: write
      questions:
      - Can I link shifts together so they form a single shift?
      - What does a linked shift need, like start and end times?
      instructions:
      - text: Link shifts {sourceShiftIds} into new shift {newShift}.
        slots:
          sourceShiftIds: requestBody.sourceShiftIds
          newShift: requestBody.newShift
      - text: Link shifts {sourceShiftIds} with override {override}.
        slots:
          sourceShiftIds: requestBody.sourceShiftIds
          override: requestBody.override
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:open'].post
  update:
    x-apievangelist-phrasing:
      intent: List open shifts
      effect: read
      questions:
      - Which shifts are still open for staff to take?
      - Can I list open shifts for one employee?
      instructions:
      - text: List open shifts.
      - text: List open shifts for employee {employee} from {start} to {end}.
        slots:
          employee: requestBody.employee
          start: requestBody.start
          end: requestBody.end
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:publish'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish shifts to staff
      effect: write
      questions:
      - How do I publish shifts so staff can see them?
      - Can I choose whether to notify staff when shifts are published?
      instructions:
      - text: Publish shifts {shiftIds}.
        slots:
          shiftIds: requestBody.shiftIds
      - text: Publish shifts {shiftIds} with notification mode {notificationMode}.
        slots:
          shiftIds: requestBody.shiftIds
          notificationMode: requestBody.notificationMode
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:resave'].post
  update:
    x-apievangelist-phrasing:
      intent: Resave shifts
      effect: write
      questions:
      - Can I resave shifts so they are reprocessed?
      - Does resaving return the shifts that were resaved?
      instructions:
      - text: Resave shifts {shifts}.
        slots:
          shifts: requestBody.shifts
      - text: Reprocess the shifts {shifts} in the background.
        slots:
          shifts: requestBody.shifts
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:split'].post
  update:
    x-apievangelist-phrasing:
      intent: Split a shift into several
      effect: write
      questions:
      - Can I split one shift into multiple shifts?
      - What does a split shift need, like new shift times?
      instructions:
      - text: Split shift {sourceShiftId} into {newShifts}.
        slots:
          sourceShiftId: requestBody.sourceShiftId
          newShifts: requestBody.newShifts
      - text: Split shift {sourceShiftId} with override {override}.
        slots:
          sourceShiftId: requestBody.sourceShiftId
          override: requestBody.override
      method: generated
      generated: '2026-11-17'
- target: $.paths['/management/v2/shifts:validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate external shifts
      effect: read
      questions:
      - Can I check external shifts before importing them?
      - What does validating external shifts return?
      instructions:
      - text: Validate external shifts {shifts}.
        slots:
          shifts: requestBody.shifts
      - text: Check these imported shifts {shifts} for validity.
        slots:
          shifts: requestBody.shifts
      method: generated
      generated: '2026-11-17'
- target: $.paths['/schedule/v2/me/shifts:search'].post
  update:
    x-apievangelist-phrasing:
      intent: Get my own schedule
      effect: read
      questions:
      - What shifts are in my schedule?
      - Can I see my schedule for a date range?
      instructions:
      - text: Show my schedule from {start} to {end}.
        slots:
          start: requestBody.start
          end: requestBody.end
      - text: Show my schedule for locations {locationIds}.
        slots:
          locationIds: requestBody.locationIds
      method: generated
      generated: '2026-11-17'

Work with this as data

Every overlay here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for openapi overlays

4 MCP tools reach this
  • find_overlaysBrowse and filter every overlay in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This overlay
curl "https://apis.io/api/v1/overlays/deputy-shifts-api-phrasing-overlay"
All openapi overlays
curl "https://apis.io/api/v1/overlays?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.