# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for GitHub v3 REST Gists API
  version: 1.0.0
extends: openapi/github-gists-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-24'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 20
- target: $.paths['/gists'].get
  update:
    x-apievangelist-phrasing:
      intent: List my gists
      effect: read
      questions:
      - Which gists have I created?
      - Can I see only the gists I've updated since last week?
      instructions:
      - text: List my gists.
      - text: Show my gists updated since {since}.
        slots:
          since: query.since
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a gist
      effect: write
      questions:
      - How do I share a code snippet as a new gist?
      - Can I create a secret gist that holds several files?
      instructions:
      - text: Create a new gist with files {files}.
        slots:
          files: requestBody.files
      - text: Create a gist described as {description} containing {files}, public set to {public}.
        slots:
          description: requestBody.description
          files: requestBody.files
          public: requestBody.public
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/public'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent public gists from everyone
      effect: read
      questions:
      - What public gists have people shared most recently?
      - Can I browse all public gists posted after a certain date?
      instructions:
      - text: List the most recent public gists from all users.
      - text: Show public gists posted since {since}.
        slots:
          since: query.since
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/starred'].get
  update:
    x-apievangelist-phrasing:
      intent: List gists I've starred
      effect: read
      questions:
      - Which gists have I starred?
      - Can I find the snippets I bookmarked with a star since a given date?
      instructions:
      - text: List the gists I've starred.
      - text: Show my starred gists updated since {since}.
        slots:
          since: query.since
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a gist and its files
      effect: read
      questions:
      - What files and content are inside a particular gist?
      - Can I fetch the current version of a gist by its ID?
      instructions:
      - text: Show me gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Get the files and contents of gist {gist_id}.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a gist
      effect: destructive
      questions:
      - How do I delete a gist I no longer need?
      - Can I remove a gist I posted by mistake?
      instructions:
      - text: Delete gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Permanently remove my gist {gist_id}.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a gist's description or files
      effect: write
      questions:
      - Can I edit the files in a gist I already posted?
      - Is it possible to rename or remove a file inside an existing gist?
      instructions:
      - text: Change the description of gist {gist_id} to {description}.
        slots:
          gist_id: path.gist_id
          description: requestBody.description
      - text: Update the files in existing gist {gist_id} to {files}.
        slots:
          gist_id: path.gist_id
          files: requestBody.files
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on a gist
      effect: read
      questions:
      - What have people commented on a gist?
      - Can I read the full discussion under a gist?
      instructions:
      - text: List the comments on gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Show the discussion under gist {gist_id}.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on a gist
      effect: write
      questions:
      - How can I leave a comment on someone's gist?
      - Can I reply to a gist with a note?
      instructions:
      - text: Comment {body} on gist {gist_id}.
        slots:
          gist_id: path.gist_id
          body: requestBody.body
      - text: Post a new comment on gist {gist_id} saying {body}.
        slots:
          gist_id: path.gist_id
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/comments/{comment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one gist comment
      effect: read
      questions:
      - What does a specific comment on a gist say?
      - Can I fetch a single gist comment by its ID?
      instructions:
      - text: Show comment {comment_id} on gist {gist_id}.
        slots:
          gist_id: path.gist_id
          comment_id: path.comment_id
      - text: Get the text of gist {gist_id} comment {comment_id}.
        slots:
          gist_id: path.gist_id
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/comments/{comment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a gist comment
      effect: destructive
      questions:
      - Can I delete a comment I left on a gist?
      - What's the way to remove an unwanted comment from my gist?
      instructions:
      - text: Delete comment {comment_id} from gist {gist_id}.
        slots:
          gist_id: path.gist_id
          comment_id: path.comment_id
      - text: Remove gist {gist_id} comment {comment_id}.
        slots:
          gist_id: path.gist_id
          comment_id: path.comment_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/comments/{comment_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a gist comment
      effect: write
      questions:
      - Can I fix a typo in a comment I already posted on a gist?
      - Is editing an existing gist comment supported?
      instructions:
      - text: Change comment {comment_id} on gist {gist_id} to say {body}.
        slots:
          gist_id: path.gist_id
          comment_id: path.comment_id
          body: requestBody.body
      - text: Edit my existing gist comment {comment_id} on {gist_id} with new text {body}.
        slots:
          gist_id: path.gist_id
          comment_id: path.comment_id
          body: requestBody.body
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/commits'].get
  update:
    x-apievangelist-phrasing:
      intent: List a gist's revision history
      effect: read
      questions:
      - How has a gist changed over time — what commits does it have?
      - Can I see who edited a gist and when?
      instructions:
      - text: List the commits of gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Show the revision history of gist {gist_id}.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/forks'].get
  update:
    x-apievangelist-phrasing:
      intent: List forks of a gist
      effect: read
      questions:
      - Who has forked a particular gist?
      - Can I see all the copies people made of my gist?
      instructions:
      - text: List the forks of gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Show everyone who forked gist {gist_id}.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/forks'].post
  update:
    x-apievangelist-phrasing:
      intent: Fork a gist
      effect: write
      questions:
      - How do I make my own copy of someone else's gist?
      - Can I fork a gist so I can edit it separately?
      instructions:
      - text: Fork gist {gist_id} into my account.
        slots:
          gist_id: path.gist_id
      - text: Make my own copy of gist {gist_id}.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/star'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether I've starred a gist
      effect: read
      questions:
      - Have I already starred a given gist?
      - Is this gist among my stars?
      instructions:
      - text: Check whether I've starred gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Tell me if gist {gist_id} is in my stars.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/star'].put
  update:
    x-apievangelist-phrasing:
      intent: Star a gist
      effect: write
      questions:
      - Can I star a gist to find it again later?
      - What's the call to bookmark a gist with a star?
      instructions:
      - text: Star gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Add gist {gist_id} to my starred gists.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/star'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unstar a gist
      effect: destructive
      questions:
      - How do I take my star off a gist?
      - Can I remove a gist from my starred list?
      instructions:
      - text: Unstar gist {gist_id}.
        slots:
          gist_id: path.gist_id
      - text: Remove gist {gist_id} from my stars.
        slots:
          gist_id: path.gist_id
      method: generated
      generated: '2026-09-24'
- target: $.paths['/gists/{gist_id}/{sha}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specific revision of a gist
      effect: read
      questions:
      - What did a gist look like at an earlier commit?
      - Can I fetch an older version of a gist by its revision SHA?
      instructions:
      - text: Show gist {gist_id} as it was at revision {sha}.
        slots:
          gist_id: path.gist_id
          sha: path.sha
      - text: Get the files of gist {gist_id} at commit {sha}.
        slots:
          gist_id: path.gist_id
          sha: path.sha
      method: generated
      generated: '2026-09-24'
- target: $.paths['/users/{username}/gists'].get
  update:
    x-apievangelist-phrasing:
      intent: List another user's public gists
      effect: read
      questions:
      - What public gists has a particular user shared?
      - Can I see someone's gists updated since a certain date?
      instructions:
      - text: List the public gists of {username}.
        slots:
          username: path.username
      - text: Show gists by {username} updated since {since}.
        slots:
          username: path.username
          since: query.since
      method: generated
      generated: '2026-09-24'