# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Postman APIs API
  version: 1.0.0
extends: openapi/postman-apis-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: 28
- target: $.paths['/apis'].get
  update:
    x-apievangelist-phrasing:
      intent: List the APIs in a workspace
      effect: read
      questions:
      - Which APIs exist in my Postman workspace?
      - Can I see only the API Builder APIs a particular teammate created in a workspace?
      - How do I page through every API defined in one workspace?
      instructions:
      - text: List all APIs in workspace {workspaceId}.
        slots:
          workspaceId: query.workspaceId
      - text: Show the APIs in workspace {workspaceId} created by user {createdBy}.
        slots:
          workspaceId: query.workspaceId
          createdBy: query.createdBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new API in a workspace
      effect: write
      questions:
      - How do I create a new API in the API Builder programmatically?
      - Can I give a new API a summary and description when I create it?
      instructions:
      - text: Create an API called {name} in workspace {workspaceId}.
        slots:
          name: requestBody.name
          workspaceId: query.workspaceId
      - text: Add a new API named {name} to workspace {workspaceId} with the summary {summary}.
        slots:
          name: requestBody.name
          workspaceId: query.workspaceId
          summary: requestBody.summary
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one API
      effect: read
      questions:
      - What versions, schemas and collections does one of my API Builder APIs have?
      - Why does a Git-connected API only return versions and Git info when I fetch it?
      instructions:
      - text: Show me the details of API {apiId}.
        slots:
          apiId: path.apiId
      - text: Fetch API {apiId} including its {include} information.
        slots:
          apiId: path.apiId
          include: query.include
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe an API
      effect: write
      questions:
      - How can I rename an existing API in the API Builder?
      - Can I change an API's summary after it has been created?
      instructions:
      - text: Rename API {apiId} to {name}.
        slots:
          apiId: path.apiId
          name: requestBody.name
      - text: Update the description of API {apiId} to {description}, keeping the name {name}.
        slots:
          apiId: path.apiId
          description: requestBody.description
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an API
      effect: destructive
      questions:
      - What's the way to permanently remove an API from the API Builder?
      - What does the response look like when an API is deleted successfully?
      instructions:
      - text: Delete API {apiId}.
        slots:
          apiId: path.apiId
      - text: Remove the API {apiId} from my workspace entirely.
        slots:
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/collections'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a collection to an API
      effect: write
      questions:
      - How do I attach a collection to one of my API Builder APIs?
      - Can I copy an existing workspace collection into an API or generate one from its schema?
      instructions:
      - text: Add a collection to API {apiId}.
        slots:
          apiId: path.apiId
      - text: Copy one of my workspace collections into API {apiId}.
        slots:
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/collections/{collectionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a collection attached to an API
      effect: read
      questions:
      - How do I read a collection that is attached to an API?
      - Can I get the copy of an API's collection that was published in a specific version?
      instructions:
      - text: Get collection {collectionId} attached to API {apiId}.
        slots:
          collectionId: path.collectionId
          apiId: path.apiId
      - text: Show collection {collectionId} of API {apiId} as published in version {versionId}.
        slots:
          collectionId: path.collectionId
          apiId: path.apiId
          versionId: query.versionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/collections/{collectionId}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on an API's collection
      effect: read
      questions:
      - What have reviewers commented on the collection attached to my API?
      - Can I pull every comment thread from an API's collection?
      instructions:
      - text: List the comments on collection {collectionId} of API {apiId}.
        slots:
          collectionId: path.collectionId
          apiId: path.apiId
      - text: Show all feedback left on API {apiId}'s collection {collectionId}.
        slots:
          apiId: path.apiId
          collectionId: path.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/collections/{collectionId}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on an API's collection
      effect: write
      questions:
      - How do I leave a comment on a collection that belongs to an API?
      - Can I reply inside an existing comment thread on an API's collection?
      - What is the character limit for a comment on an API collection?
      instructions:
      - text: Post the comment {body} on collection {collectionId} of API {apiId}.
        slots:
          body: requestBody.body
          collectionId: path.collectionId
          apiId: path.apiId
      - text: Reply {body} to thread {threadId} on API {apiId}'s collection {collectionId}.
        slots:
          body: requestBody.body
          threadId: requestBody.threadId
          apiId: path.apiId
          collectionId: path.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/collections/{collectionId}/comments/{commentId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment on an API's collection
      effect: write
      questions:
      - How do I edit a comment I already left on an API's collection?
      - Can I change the text of an existing collection comment within an API?
      instructions:
      - text: Change comment {commentId} on collection {collectionId} of API {apiId} to say {body}.
        slots:
          commentId: path.commentId
          collectionId: path.collectionId
          apiId: path.apiId
          body: requestBody.body
      - text: Rewrite my API collection comment {commentId} (API {apiId}, collection {collectionId}) as {body}.
        slots:
          commentId: path.commentId
          apiId: path.apiId
          collectionId: path.collectionId
          body: requestBody.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/collections/{collectionId}/comments/{commentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment on an API's collection
      effect: destructive
      questions:
      - How do I remove a comment from a collection attached to an API?
      - Does deleting the first comment on an API collection wipe out the whole thread?
      instructions:
      - text: Delete comment {commentId} from collection {collectionId} of API {apiId}.
        slots:
          commentId: path.commentId
          collectionId: path.collectionId
          apiId: path.apiId
      - text: Remove the thread started by comment {commentId} on API {apiId}'s collection {collectionId}.
        slots:
          commentId: path.commentId
          apiId: path.apiId
          collectionId: path.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/collections/{collectionId}/sync-with-schema-tasks'].put
  update:
    x-apievangelist-phrasing:
      intent: Sync an API's collection with its schema
      effect: write
      questions:
      - How do I bring an API's collection back in line with the API schema after the schema changed?
      - Is syncing an API collection to its schema asynchronous, and how do I track it?
      instructions:
      - text: Sync collection {collectionId} with the schema of API {apiId}.
        slots:
          collectionId: path.collectionId
          apiId: path.apiId
      - text: Regenerate API {apiId}'s collection {collectionId} from its current schema.
        slots:
          apiId: path.apiId
          collectionId: path.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/comments'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments on an API
      effect: read
      questions:
      - What comments have teammates left on my API itself?
      - Can I read all the discussion threads on an API in the API Builder?
      instructions:
      - text: List the comments on API {apiId}.
        slots:
          apiId: path.apiId
      - text: Show every discussion thread on API {apiId}.
        slots:
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/comments'].post
  update:
    x-apievangelist-phrasing:
      intent: Comment on an API
      effect: write
      questions:
      - How do I add a comment directly on an API rather than on one of its collections?
      - Can I reply to an existing comment thread on an API?
      instructions:
      - text: Comment {body} on API {apiId}.
        slots:
          body: requestBody.body
          apiId: path.apiId
      - text: Reply {body} in thread {threadId} on API {apiId}.
        slots:
          body: requestBody.body
          threadId: requestBody.threadId
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/comments/{commentId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment on an API
      effect: write
      questions:
      - I made a typo in a comment on an API — can I fix it?
      - Can I update an API-level comment and its tags?
      instructions:
      - text: Update comment {commentId} on API {apiId} to read {body}.
        slots:
          commentId: path.commentId
          apiId: path.apiId
          body: requestBody.body
      - text: Edit my API comment {commentId} on {apiId} so it says {body}.
        slots:
          commentId: path.commentId
          apiId: path.apiId
          body: requestBody.body
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/comments/{commentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment on an API
      effect: destructive
      questions:
      - How do I delete a comment posted on an API?
      - What happens to replies when I delete the first comment of a thread on an API?
      instructions:
      - text: Delete comment {commentId} from API {apiId}.
        slots:
          commentId: path.commentId
          apiId: path.apiId
      - text: Remove API {apiId}'s comment {commentId} and its thread.
        slots:
          apiId: path.apiId
          commentId: path.commentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/schemas'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a schema to an API
      effect: write
      questions:
      - How do I add a schema definition to an API in the API Builder?
      - Can I upload a multi-file schema when creating an API's schema?
      instructions:
      - text: 'Create a {type} schema for API {apiId} from these files: {files}.'
        slots:
          type: requestBody.type
          apiId: path.apiId
          files: requestBody.files
      - text: Attach a new {type} schema to API {apiId}.
        slots:
          type: requestBody.type
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/schemas/{schemaId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an API's schema
      effect: read
      questions:
      - How do I retrieve the schema of an API including its metadata?
      - Can I get an API schema bundled into a single file?
      - Which schema was published in a given API version?
      instructions:
      - text: Get schema {schemaId} of API {apiId}.
        slots:
          schemaId: path.schemaId
          apiId: path.apiId
      - text: Return API {apiId}'s schema {schemaId} as a bundled document.
        slots:
          apiId: path.apiId
          schemaId: path.schemaId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/schemas/{schemaId}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List the files in an API schema
      effect: read
      questions:
      - What files make up my API's schema?
      - Can I list the schema files as they were in a published API version?
      instructions:
      - text: List the files in schema {schemaId} of API {apiId}.
        slots:
          schemaId: path.schemaId
          apiId: path.apiId
      - text: Show the schema files of API {apiId} schema {schemaId} for version {versionId}.
        slots:
          apiId: path.apiId
          schemaId: path.schemaId
          versionId: query.versionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/schemas/{schemaId}/files/{file-path}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one file in an API schema
      effect: read
      questions:
      - How do I read the contents of a single file inside an API schema?
      - Can I see a schema file's contents as they were in an older API version?
      instructions:
      - text: Show the contents of {file-path} in schema {schemaId} of API {apiId}.
        slots:
          file-path: path.file-path
          schemaId: path.schemaId
          apiId: path.apiId
      - text: Open schema file {file-path} of API {apiId} schema {schemaId} at version {versionId}.
        slots:
          file-path: path.file-path
          apiId: path.apiId
          schemaId: path.schemaId
          versionId: query.versionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/schemas/{schemaId}/files/{file-path}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or overwrite a file in an API schema
      effect: write
      questions:
      - How do I upload or replace a file inside an API's schema?
      - Can I mark a schema file as the root file of an API schema?
      instructions:
      - text: Write {content} to file {file-path} in schema {schemaId} of API {apiId}.
        slots:
          content: requestBody.content
          file-path: path.file-path
          schemaId: path.schemaId
          apiId: path.apiId
      - text: Add a new schema file at {file-path} to API {apiId} schema {schemaId}.
        slots:
          file-path: path.file-path
          apiId: path.apiId
          schemaId: path.schemaId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/schemas/{schemaId}/files/{file-path}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a file from an API schema
      effect: destructive
      questions:
      - How do I remove an unused file from an API's schema?
      - Can I delete just one file from a multi-file API schema?
      instructions:
      - text: Delete file {file-path} from schema {schemaId} of API {apiId}.
        slots:
          file-path: path.file-path
          schemaId: path.schemaId
          apiId: path.apiId
      - text: Remove the schema file {file-path} in API {apiId}'s schema {schemaId}.
        slots:
          file-path: path.file-path
          apiId: path.apiId
          schemaId: path.schemaId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/tasks/{taskId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an API's background task status
      effect: read
      questions:
      - Has the version publish or collection sync I started on my API finished yet?
      - Where do I poll the progress of an asynchronous API Builder task?
      instructions:
      - text: Check the status of task {taskId} on API {apiId}.
        slots:
          taskId: path.taskId
          apiId: path.apiId
      - text: Tell me whether API {apiId}'s background task {taskId} has completed.
        slots:
          apiId: path.apiId
          taskId: path.taskId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List an API's published versions
      effect: read
      questions:
      - Which versions of my API have been published?
      - Can I page through a long list of API versions?
      instructions:
      - text: List all published versions of API {apiId}.
        slots:
          apiId: path.apiId
      - text: Show the first {limit} versions of API {apiId}.
        slots:
          limit: query.limit
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Publish a new API version
      effect: write
      questions:
      - How do I publish a new version of an API from its current state?
      - Why does creating an API version return 202 Accepted with a polling link?
      instructions:
      - text: Publish a new version of API {apiId}.
        slots:
          apiId: path.apiId
      - text: Cut a release version for API {apiId} and give me the task to poll.
        slots:
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/versions/{versionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one API version
      effect: read
      questions:
      - What is in a specific published version of my API?
      - Why do I get a 302 redirect when fetching an API version that is still pending?
      instructions:
      - text: Get version {versionId} of API {apiId}.
        slots:
          versionId: path.versionId
          apiId: path.apiId
      - text: Show me the release details of API {apiId} version {versionId}.
        slots:
          apiId: path.apiId
          versionId: path.versionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/versions/{versionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename a version or edit its release notes
      effect: write
      questions:
      - How do I change the release notes on a published API version?
      - Can I rename an API version once it has been published?
      instructions:
      - text: Rename version {versionId} of API {apiId} to {name}.
        slots:
          versionId: path.versionId
          apiId: path.apiId
          name: requestBody.name
      - text: Set the release notes of API {apiId} version {versionId} (named {name}) to {releaseNotes}.
        slots:
          apiId: path.apiId
          versionId: path.versionId
          name: requestBody.name
          releaseNotes: requestBody.releaseNotes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/versions/{versionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an API version
      effect: destructive
      questions:
      - Is it possible to delete an API version I published by mistake?
      - Can I delete an API version that is still pending publication?
      instructions:
      - text: Delete version {versionId} of API {apiId}.
        slots:
          versionId: path.versionId
          apiId: path.apiId
      - text: Remove the published release {versionId} from API {apiId}.
        slots:
          versionId: path.versionId
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'