# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Outsystems Assets API
  version: 1.0.0
extends: openapi/outsystems-assets-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 22
- target: $.paths['/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets in the repository
      effect: read
      questions:
      - What apps, libraries and agents are in my ODC asset repository?
      - Can I filter my assets by type or by portfolio?
      - Which assets have a name or description mentioning a keyword?
      instructions:
      - text: List all my assets of type {assetTypes}.
        slots:
          assetTypes: query.assetTypes
      - text: Find assets whose name contains {nameContains}.
        slots:
          nameContains: query.nameContains
      - text: Show the assets that belong to portfolio {portfolioKeys}.
        slots:
          portfolioKeys: query.portfolioKeys
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an asset or a new asset revision
      effect: write
      questions:
      - How do I upload an OML or XIF file as a new revision of an app?
      - Can I create a brand-new asset from a template or as an empty one?
      - Is it possible to add a commit message and release notes when saving a revision?
      instructions:
      - text: Create a new asset revision from the uploaded file at {fileUri}.
        slots:
          fileUri: requestBody.fileUri
      - text: Save a new revision from {fileUri} with commit message {commitMessage}.
        slots:
          fileUri: requestBody.fileUri
          commitMessage: requestBody.commitMessage
      - text: Create a new asset in portfolio {portfolioKey} from the file at {fileUri}.
        slots:
          portfolioKey: requestBody.portfolioKey
          fileUri: requestBody.fileUri
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an asset's details
      effect: read
      questions:
      - How do I look up a single asset's details by its key?
      - What information does ODC hold about one specific app or library?
      instructions:
      - text: Get the details of asset {assetKey}.
        slots:
          assetKey: path.assetKey
      - text: Show me asset {assetKey} with its current details.
        slots:
          assetKey: path.assetKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an asset permanently
      effect: destructive
      questions:
      - Can I permanently delete an app and all of its runtime data?
      - What happens to the stages an asset is published to when I delete it?
      instructions:
      - text: Delete asset {assetKey} permanently.
        slots:
          assetKey: path.assetKey
      - text: Remove asset {assetKey} from the repository and all its stages.
        slots:
          assetKey: path.assetKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/highest-tag-revision'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an asset's highest-tagged revision
      effect: read
      questions:
      - Which revision of my app carries the highest version tag?
      - How do I find the most recent tagged release of an asset rather than the latest save?
      instructions:
      - text: Get the highest-tagged revision of asset {assetKey}.
        slots:
          assetKey: path.assetKey
      - text: Show the top tagged version of {assetKey}.
        slots:
          assetKey: path.assetKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/latest-revision'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an asset's latest revision
      effect: read
      questions:
      - What is the newest revision saved for an asset, tagged or not?
      - Can I fetch only the latest revision record of an app?
      instructions:
      - text: Get the latest revision of asset {assetKey}.
        slots:
          assetKey: path.assetKey
      - text: Show me the most recent revision saved for {assetKey}.
        slots:
          assetKey: path.assetKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a specific asset revision
      effect: read
      questions:
      - How do I retrieve one exact numbered revision of an asset?
      - Can I look at an older revision of my app by its revision number?
      instructions:
      - text: Get revision {revisionNumber} of asset {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Show me asset {assetKey} as it was at revision {revisionNumber}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Tag a revision or edit its release notes
      effect: write
      questions:
      - How do I set a version tag on an existing asset revision?
      - Can I clear a revision's version tag by setting it to null?
      - Can I change the release notes or commit message of a revision after it was saved?
      instructions:
      - text: Tag revision {revisionNumber} of asset {assetKey} as version {tag}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
          tag: requestBody.tag
      - text: Update the release notes of revision {revisionNumber} of {assetKey} to {releaseNotes}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
          releaseNotes: requestBody.releaseNotes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/icon'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the icon of an asset revision
      effect: read
      questions:
      - Where can I download the icon image used by a given app revision?
      - Can I fetch the app icon for a particular revision number?
      instructions:
      - text: Get the icon for revision {revisionNumber} of asset {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Download the app icon of {assetKey} at revision {revisionNumber}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/metadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the metadata of an asset revision
      effect: read
      questions:
      - What metadata is stored for a particular asset revision?
      - Can I inspect the revision metadata of an app without downloading its source?
      instructions:
      - text: Get the metadata for revision {revisionNumber} of asset {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Show the revision metadata of {assetKey} at revision {revisionNumber}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/release-notes'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the release notes of a revision
      effect: read
      questions:
      - What release notes were written for a given revision of my app?
      - Can I pull the changelog text attached to one asset revision?
      instructions:
      - text: Get the release notes for revision {revisionNumber} of asset {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Show what changed in {assetKey} revision {revisionNumber} according to its release notes.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/signature'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the signature of an asset revision
      effect: read
      questions:
      - How can I get the signature that identifies a specific asset revision?
      - Is there a way to verify an asset revision using its signature?
      instructions:
      - text: Get the signature for revision {revisionNumber} of asset {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Fetch the revision signature of {assetKey} at {revisionNumber}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/source-code'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an asset revision's source
      effect: read
      questions:
      - Can I download the source model of an app revision from ODC?
      - What permission is needed to fetch an asset revision's source code?
      instructions:
      - text: Get the source code for revision {revisionNumber} of asset {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Download the source of {assetKey} at revision {revisionNumber}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions'].get
  update:
    x-apievangelist-phrasing:
      intent: List an asset's revision history
      effect: read
      questions:
      - How do I see the full revision history of one app?
      - Can I list only the tagged revisions of an asset?
      - Which revisions of an asset were saved within a date range?
      instructions:
      - text: List all revisions of asset {assetKey}.
        slots:
          assetKey: path.assetKey
      - text: List the tagged revisions of {assetKey} only.
        slots:
          assetKey: path.assetKey
      - text: Show revisions of {assetKey} saved since {revisionDateTimeSince}.
        slots:
          assetKey: path.assetKey
          revisionDateTimeSince: query.revisionDateTimeSince
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up revisions of several assets at once
      effect: read
      questions:
      - Can I fetch specific revisions of many different assets in one request?
      - How do I look up asset versions by a mix of key, digest and revision number?
      instructions:
      - text: 'Look up these asset revisions in one batch: {assetVersionFilters}.'
        slots:
          assetVersionFilters: requestBody.assetVersionFilters
      - text: Search asset versions matching the key and revision pairs {assetVersionFilters}.
        slots:
          assetVersionFilters: requestBody.assetVersionFilters
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revision}/analysis-summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a revision's code analysis summary
      effect: read
      questions:
      - What quality score did a specific app revision get?
      - How many high-severity findings does one revision of my asset have?
      instructions:
      - text: Get the analysis summary for revision {revision} of asset {assetKey}.
        slots:
          revision: path.revision
          assetKey: path.assetKey
      - text: Show the findings breakdown by severity for {assetKey} revision {revision}.
        slots:
          assetKey: path.assetKey
          revision: path.revision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/consumers'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets that consume an asset
      effect: read
      questions:
      - Which apps depend on this library across any of its revisions?
      - Can I see consumers of an asset in one particular stage?
      instructions:
      - text: List all assets that consume asset {assetKey}.
        slots:
          assetKey: path.assetKey
      - text: Show consumers of {assetKey} in stage {environmentKey}.
        slots:
          assetKey: path.assetKey
          environmentKey: query.environmentKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/producer-graph'].get
  update:
    x-apievangelist-phrasing:
      intent: Map an asset revision's dependency graph
      effect: read
      questions:
      - How do I get the full dependency graph of producers for an app revision?
      - Can I limit how deep the producer graph goes?
      instructions:
      - text: Build the producer dependency graph for revision {revisionNumber} of {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Show the producer graph of {assetKey} revision {revisionNumber} up to depth {maxDepth}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
          maxDepth: query.maxDepth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/producers'].get
  update:
    x-apievangelist-phrasing:
      intent: List producers a revision depends on
      effect: read
      questions:
      - What libraries does a given app revision rely on, directly or indirectly?
      - Can I get a flat list of producer assets for one revision?
      instructions:
      - text: List the producer assets that revision {revisionNumber} of {assetKey} depends on.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Give me a flat list of dependencies for {assetKey} at revision {revisionNumber}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/consumers'].get
  update:
    x-apievangelist-phrasing:
      intent: List consumers of one asset revision
      effect: read
      questions:
      - Which apps consume a specific revision of my library?
      - Is anything still using an older revision of this asset?
      instructions:
      - text: List the consumers of revision {revisionNumber} of asset {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Show which assets use {assetKey} revision {revisionNumber} in stage {environmentKey}.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
          environmentKey: query.environmentKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/public-elements'].get
  update:
    x-apievangelist-phrasing:
      intent: List public elements an asset exposes
      effect: read
      questions:
      - What public actions and elements does a library revision expose to others?
      - Can I include hidden public elements when listing what an asset exposes?
      instructions:
      - text: List the public elements exposed by revision {revisionNumber} of {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Show everything {assetKey} revision {revisionNumber} exposes, including hidden elements.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'
- target: $.paths['/assets/{assetKey}/revisions/{revisionNumber}/referenced-elements'].get
  update:
    x-apievangelist-phrasing:
      intent: List elements a revision references
      effect: read
      questions:
      - Which public elements from other assets does my app revision reference in the IDE?
      - What external actions does a given revision actually use?
      instructions:
      - text: List the public elements referenced by revision {revisionNumber} of {assetKey}.
        slots:
          revisionNumber: path.revisionNumber
          assetKey: path.assetKey
      - text: Show which external elements {assetKey} revision {revisionNumber} references.
        slots:
          assetKey: path.assetKey
          revisionNumber: path.revisionNumber
      method: generated
      generated: '2026-10-01'