# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Nylas Calendar API
  version: 1.0.0
extends: openapi/nylas-calendar-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: 7
- target: $.paths['/v3/grants/{grant_id}/calendars'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's calendars
      effect: read
      questions:
      - What calendars does this connected account have?
      - Can I find calendars that carry a specific metadata key and value?
      instructions:
      - text: List all calendars for grant {grant}.
        slots:
          grant: path.grant_id
      - text: Find calendars on {grant} with metadata {metadata_pair}.
        slots:
          grant: path.grant_id
          metadata_pair: query.metadata_pair
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/calendars'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new calendar
      effect: write
      questions:
      - How do I add a new calendar to a user's account?
      - Can I set a timezone and location when creating a calendar?
      instructions:
      - text: Create a calendar named {name} for grant {grant}.
        slots:
          name: requestBody.name
          grant: path.grant_id
      - text: Create calendar {name} on {grant} in timezone {timezone}.
        slots:
          name: requestBody.name
          grant: path.grant_id
          timezone: requestBody.timezone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/calendars/{calendar_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one calendar's details
      effect: read
      questions:
      - What are the settings of a user's primary calendar?
      - Can I fetch a single calendar by its ID?
      instructions:
      - text: Show calendar {calendar} for grant {grant}.
        slots:
          calendar: path.calendar_id
          grant: path.grant_id
      - text: Get the details of calendar {calendar} on {grant}.
        slots:
          calendar: path.calendar_id
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/calendars/{calendar_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a calendar's name, color or details
      effect: write
      questions:
      - Can I change the color of an existing calendar?
      - Is renaming a user's primary calendar allowed for Microsoft accounts?
      instructions:
      - text: Rename calendar {calendar} on grant {grant} to {name}.
        slots:
          calendar: path.calendar_id
          grant: path.grant_id
          name: requestBody.name
      - text: Set the color of calendar {calendar} on {grant} to {hex_color}.
        slots:
          calendar: path.calendar_id
          grant: path.grant_id
          hex_color: requestBody.hex_color
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/calendars/{calendar_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a calendar
      effect: destructive
      questions:
      - Can I delete a secondary calendar from a user's account?
      - Why can't I delete the primary calendar?
      instructions:
      - text: Delete calendar {calendar} from grant {grant}.
        slots:
          calendar: path.calendar_id
          grant: path.grant_id
      - text: Remove the calendar {calendar} on {grant}.
        slots:
          calendar: path.calendar_id
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/calendars/availability'].post
  update:
    x-apievangelist-phrasing:
      intent: Find open time slots across participants
      effect: read
      questions:
      - When are several teammates all free for a 30-minute meeting?
      - Can I get availability slots rounded to the nearest 15 minutes?
      - How do I find common open times for a group between two dates?
      instructions:
      - text: Find {duration_minutes}-minute slots when {participants} are free between {start_time} and {end_time}.
        slots:
          duration_minutes: requestBody.duration_minutes
          participants: requestBody.participants
          start_time: requestBody.start_time
          end_time: requestBody.end_time
      - text: Check availability for {participants} from {start_time} to {end_time} in {duration_minutes}-minute blocks every {interval_minutes} minutes.
        slots:
          participants: requestBody.participants
          start_time: requestBody.start_time
          end_time: requestBody.end_time
          duration_minutes: requestBody.duration_minutes
          interval_minutes: requestBody.interval_minutes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v3/grants/{grant_id}/calendars/free-busy'].post
  update:
    x-apievangelist-phrasing:
      intent: Get free/busy blocks for email addresses
      effect: read
      questions:
      - Which times are people busy according to their calendars?
      - Can tentative events count as busy in a free/busy lookup?
      instructions:
      - text: Get the free/busy schedule of {emails} from {start_time} to {end_time} using grant {grant}.
        slots:
          emails: requestBody.emails
          start_time: requestBody.start_time
          end_time: requestBody.end_time
          grant: path.grant_id
      - text: Show busy blocks for {emails} between {start_time} and {end_time} via {grant}, counting tentative as busy.
        slots:
          emails: requestBody.emails
          start_time: requestBody.start_time
          end_time: requestBody.end_time
          grant: path.grant_id
      method: generated
      generated: '2026-09-26'