# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Postman Specs API
  version: 1.0.0
extends: openapi/postman-specs-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: 24
- target: $.paths['/apis/{apiId}/spec-migrations'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an API Builder to Spec Hub migration
      effect: read
      questions:
      - Has my API Builder definition finished migrating to Spec Hub?
      - Where can I see whether a Spec Hub migration failed or is still running?
      instructions:
      - text: Check the Spec Hub migration status of API {apiId}.
        slots:
          apiId: path.apiId
      - text: Tell me if API Builder API {apiId} has been moved to Spec Hub yet.
        slots:
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{apiId}/spec-migrations'].post
  update:
    x-apievangelist-phrasing:
      intent: Migrate an API Builder API to Spec Hub
      effect: write
      questions:
      - How do I move a legacy API Builder definition over to Spec Hub?
      - Can I migrate an API Builder API into an existing workspace or a brand new one?
      instructions:
      - text: Migrate API Builder API {apiId} to Spec Hub.
        slots:
          apiId: path.apiId
      - text: Convert the API Builder definition of {apiId} into a Spec Hub specification.
        slots:
          apiId: path.apiId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/collections/{collectionUid}/generations/{elementType}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the spec generated from a collection
      effect: read
      questions:
      - Where do I find the OpenAPI spec that was generated from my collection?
      - Can I see which specifications have already been produced from a given collection?
      instructions:
      - text: Show the {elementType} generated from collection {collectionUid}.
        slots:
          elementType: path.elementType
          collectionUid: path.collectionUid
      - text: Get the spec that was created from collection {collectionUid} as {elementType}.
        slots:
          collectionUid: path.collectionUid
          elementType: path.elementType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/collections/{collectionUid}/generations/{elementType}'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate an OpenAPI spec from a collection
      effect: write
      questions:
      - How do I turn an existing Postman collection into an OpenAPI 3.1 specification?
      - Can I choose OpenAPI 2.0, 3.0 or 3.1 and JSON or YAML when generating a spec from a collection?
      instructions:
      - text: Generate a {elementType} named {name} from collection {collectionUid}.
        slots:
          elementType: path.elementType
          name: requestBody.name
          collectionUid: path.collectionUid
      - text: Create an {type} spec called {name} in {format} format from collection {collectionUid} as {elementType}.
        slots:
          type: requestBody.type
          name: requestBody.name
          format: requestBody.format
          collectionUid: path.collectionUid
          elementType: path.elementType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/collections/{collectionUid}/synchronizations'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a generated collection from its spec
      effect: write
      questions:
      - How do I push spec changes into the collection that was generated from it?
      - Which spec formats support syncing a generated collection?
      instructions:
      - text: Sync collection {collectionUid} with the latest version of spec {specId}.
        slots:
          collectionUid: path.collectionUid
          specId: query.specId
      - text: Refresh generated collection {collectionUid} from spec {specId}.
        slots:
          collectionUid: path.collectionUid
          specId: query.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{elementType}/{elementId}/tasks/{taskId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a spec or collection generation task
      effect: read
      questions:
      - Is the spec generation or sync task I kicked off still running?
      - How can I poll the result of an asynchronous Spec Hub task?
      instructions:
      - text: Check task {taskId} on {elementType} {elementId}.
        slots:
          taskId: path.taskId
          elementType: path.elementType
          elementId: path.elementId
      - text: Poll the generation task {taskId} for {elementType} {elementId} until it is done.
        slots:
          taskId: path.taskId
          elementType: path.elementType
          elementId: path.elementId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs'].get
  update:
    x-apievangelist-phrasing:
      intent: List the specs in a workspace
      effect: read
      questions:
      - Which API specifications live in my workspace's Spec Hub?
      - Can I page through all specs in a workspace a few at a time?
      instructions:
      - text: List all specs in workspace {workspaceId}.
        slots:
          workspaceId: query.workspaceId
      - text: Show the first {limit} Spec Hub specifications in workspace {workspaceId}.
        slots:
          limit: query.limit
          workspaceId: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a spec in Spec Hub
      effect: write
      questions:
      - How do I create a new OpenAPI or AsyncAPI specification in Spec Hub?
      - Can a Spec Hub specification span multiple files?
      instructions:
      - text: Create a {type} spec named {name} in workspace {workspaceId} with files {files}.
        slots:
          type: requestBody.type
          name: requestBody.name
          workspaceId: query.workspaceId
          files: requestBody.files
      - text: Add a new specification {name} to Spec Hub in workspace {workspaceId}.
        slots:
          name: requestBody.name
          workspaceId: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a spec's details
      effect: read
      questions:
      - What type and name does a given Spec Hub specification have?
      - Can I look up a specification's metadata by its ID?
      instructions:
      - text: Get spec {specId}.
        slots:
          specId: path.specId
      - text: Show the metadata for specification {specId}.
        slots:
          specId: path.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a spec
      effect: destructive
      questions:
      - How do I delete a specification from Spec Hub?
      - Is removing a Spec Hub specification permanent?
      instructions:
      - text: Delete spec {specId}.
        slots:
          specId: path.specId
      - text: Remove specification {specId} from Spec Hub.
        slots:
          specId: path.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a spec
      effect: write
      questions:
      - How do I rename a specification in Spec Hub?
      - Can I change a spec's name without touching its files?
      instructions:
      - text: Rename spec {specId} to {name}.
        slots:
          specId: path.specId
          name: requestBody.name
      - text: Change the title of specification {specId} to {name}.
        slots:
          specId: path.specId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/collections/{collectionId}/sync-options'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change sync settings for a spec's collection
      effect: write
      questions:
      - How do I configure how a spec's generated collection syncs with it?
      - Can I change the sync options for one collection generated from a specification?
      instructions:
      - text: Update the sync options between spec {specId} and collection {collectionId} to {syncOptions}.
        slots:
          specId: path.specId
          collectionId: path.collectionId
          syncOptions: requestBody.syncOptions
      - text: Adjust how collection {collectionId} stays in sync with spec {specId}.
        slots:
          collectionId: path.collectionId
          specId: path.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/definitions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a spec's full definition
      effect: read
      questions:
      - How do I download the complete OpenAPI or AsyncAPI definition of a spec?
      - Can I get the whole spec definition in one response instead of file by file?
      instructions:
      - text: Get the full definition of spec {specId}.
        slots:
          specId: path.specId
      - text: Export the complete API definition for specification {specId}.
        slots:
          specId: path.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List a spec's files
      effect: read
      questions:
      - What files does a multi-file specification contain?
      - Can I see the file tree of a Spec Hub specification?
      instructions:
      - text: List the files in spec {specId}.
        slots:
          specId: path.specId
      - text: Show me every file that makes up specification {specId}.
        slots:
          specId: path.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a file to a spec
      effect: write
      questions:
      - How do I add a new file to an OpenAPI or protobuf specification?
      - Does a forward slash in a spec file path create a folder?
      instructions:
      - text: Add file {path} with content {content} to spec {specId}.
        slots:
          path: requestBody.path
          content: requestBody.content
          specId: path.specId
      - text: Create a new spec file at {path} in specification {specId} containing {content}.
        slots:
          path: requestBody.path
          specId: path.specId
          content: requestBody.content
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/files/{filePath}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one file in a spec
      effect: read
      questions:
      - How do I read the contents of a single file within a specification?
      - Can I fetch just the components file of a multi-file spec?
      instructions:
      - text: Show the contents of file {filePath} in spec {specId}.
        slots:
          filePath: path.filePath
          specId: path.specId
      - text: Open spec {specId}'s file at {filePath}.
        slots:
          specId: path.specId
          filePath: path.filePath
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/files/{filePath}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a file from a spec
      effect: destructive
      questions:
      - How do I delete one file from a Spec Hub specification?
      - Can I remove a spec file without deleting the whole specification?
      instructions:
      - text: Delete file {filePath} from spec {specId}.
        slots:
          filePath: path.filePath
          specId: path.specId
      - text: Remove the spec file at {filePath} in specification {specId}.
        slots:
          filePath: path.filePath
          specId: path.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/files/{filePath}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit or rename a file in a spec
      effect: write
      questions:
      - How do I update the content of an existing file in a specification?
      - Can I rename a spec file or change it to the root file?
      instructions:
      - text: Replace the content of file {filePath} in spec {specId} with {content}.
        slots:
          filePath: path.filePath
          specId: path.specId
          content: requestBody.content
      - text: Rename spec {specId}'s file {filePath} to {name}.
        slots:
          specId: path.specId
          filePath: path.filePath
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/generations/{elementType}'].get
  update:
    x-apievangelist-phrasing:
      intent: List collections generated from a spec
      effect: read
      questions:
      - Which collections have been generated from my specification?
      - Can I see every generated collection that is linked to a spec?
      instructions:
      - text: List the {elementType} generated from spec {specId}.
        slots:
          elementType: path.elementType
          specId: path.specId
      - text: Show the first {limit} generated collections of specification {specId} ({elementType}).
        slots:
          limit: query.limit
          specId: path.specId
          elementType: path.elementType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/generations/{elementType}'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a collection from a spec
      effect: write
      questions:
      - How do I create a Postman collection from an OpenAPI 3.1 or Smithy spec?
      - Can I pass generation options when building a collection from a specification?
      instructions:
      - text: Generate a {elementType} named {name} from spec {specId} with options {options}.
        slots:
          elementType: path.elementType
          name: requestBody.name
          specId: path.specId
          options: requestBody.options
      - text: Build a new collection called {name} from specification {specId} as {elementType} using {options}.
        slots:
          name: requestBody.name
          specId: path.specId
          elementType: path.elementType
          options: requestBody.options
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/synchronizations'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a spec from its linked collection
      effect: write
      questions:
      - How do I pull changes made in a collection back into its linked specification?
      - Is syncing a spec from a collection asynchronous?
      instructions:
      - text: Sync spec {specId} with the changes in collection {collectionUid}.
        slots:
          specId: path.specId
          collectionUid: query.collectionUid
      - text: Update specification {specId} to match linked collection {collectionUid}.
        slots:
          specId: path.specId
          collectionUid: query.collectionUid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/version-tags/{tagId}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a spec snapshot by version tag
      effect: read
      questions:
      - What did my specification look like at a tagged point in time?
      - Can I retrieve the files of a spec as captured by one version tag?
      instructions:
      - text: Get the files of spec {specId} at version tag {tagId}.
        slots:
          specId: path.specId
          tagId: path.tagId
      - text: Show the snapshot of specification {specId} saved under tag {tagId}.
        slots:
          specId: path.specId
          tagId: path.tagId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/version-tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List a spec's version tags
      effect: read
      questions:
      - Which version tags have been created on my specification?
      - How can I see the history of tagged snapshots for a spec?
      instructions:
      - text: List the version tags on spec {specId}.
        slots:
          specId: path.specId
      - text: Show the latest {limit} tagged snapshots of specification {specId}.
        slots:
          limit: query.limit
          specId: path.specId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/specs/{specId}/version-tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Tag a spec version
      effect: write
      questions:
      - How do I snapshot a specification so I can track changes over time?
      - What causes a conflict when creating a spec version tag?
      instructions:
      - text: Create version tag {name} on spec {specId}.
        slots:
          name: requestBody.name
          specId: path.specId
      - text: Snapshot specification {specId} under the tag {name}.
        slots:
          specId: path.specId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'