API Evangelist conversational phrasing for v1 Config API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for v1 Config API
  version: 1.0.0
extends: openapi/here-config-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: 22
- target: $.paths['/catalogs'].get
  update:
    x-apievangelist-phrasing:
      intent: List the data catalogs I can access
      effect: read
      questions:
      - Which HERE platform catalogs does my account have access to?
      - Can I filter the catalog list by layer type or region?
      - How do I find catalogs that are marketplace ready?
      instructions:
      - text: List all catalogs I have access to.
      - text: List catalogs matching {search} sorted by {sort_by}.
        slots:
          search: query.q
          sort_by: query.sortBy
      - text: Show catalogs that contain {layer_type} layers.
        slots:
          layer_type: query.layerType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new data catalog
      effect: write
      questions:
      - How do I create a new catalog with layers on the HERE platform?
      - Is catalog creation synchronous or do I get a token to poll?
      instructions:
      - text: Create a catalog with id {id} named {name} and summary {summary}.
        slots:
          id: requestBody.id
          name: requestBody.name
          summary: requestBody.summary
      - text: Create catalog {id} called {name} with the layers {layers}.
        slots:
          id: requestBody.id
          name: requestBody.name
          layers: requestBody.layers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/context/{pageContext}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the next page of a catalog listing
      effect: read
      questions:
      - What do I do when my catalog list comes back split across pages?
      - Can I fetch a specific page of catalogs using a page context?
      instructions:
      - text: Get the catalogs page for page context {page_context}.
        slots:
          page_context: path.pageContext
      - text: Fetch the next page of my catalog list using context {page_context}.
        slots:
          page_context: path.pageContext
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a catalog's full configuration
      effect: read
      questions:
      - How can I see the layer definitions configured in one catalog?
      - What does the full configuration of a single catalog include?
      instructions:
      - text: Show the full configuration of catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Get the layers and layer types defined in catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a catalog's configuration
      effect: write
      questions:
      - How do I replace a catalog's whole configuration with a new version?
      - Does a full catalog update require resending id, name and summary?
      instructions:
      - text: Replace the configuration of catalog {catalog_hrn} with name {name} and summary {summary}.
        slots:
          catalog_hrn: path.catalogHrn
          name: requestBody.name
          summary: requestBody.summary
      - text: Send a complete new configuration for catalog {catalog_hrn} including layers {layers}.
        slots:
          catalog_hrn: path.catalogHrn
          layers: requestBody.layers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a catalog and its layers
      effect: destructive
      questions:
      - What happens to the layers when I delete a catalog?
      - Can I permanently remove a catalog I no longer need?
      instructions:
      - text: Delete catalog {catalog_hrn} and all of its layers.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Permanently remove the catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a few fields on a catalog
      effect: write
      questions:
      - Can I change just a catalog's description without resending everything?
      - How do I turn on delete protection for a catalog?
      instructions:
      - text: Change the description of catalog {catalog_hrn} to {description}.
        slots:
          catalog_hrn: path.catalogHrn
          description: requestBody.description
      - text: Set delete protection on catalog {catalog_hrn} to {delete_protected}.
        slots:
          catalog_hrn: path.catalogHrn
          delete_protected: requestBody.deleteProtected
      - text: Rename catalog {catalog_hrn} to {name}.
        slots:
          catalog_hrn: path.catalogHrn
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check whether a catalog exists
      effect: read
      questions:
      - Is there a quick way to check if a catalog HRN exists?
      - Can I test for a catalog's existence without downloading its config?
      instructions:
      - text: Check whether catalog {catalog_hrn} exists.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Confirm the HRN {catalog_hrn} points to an existing catalog.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: See whether a catalog is enabled or disabled
      effect: read
      questions:
      - Who disabled this catalog and when?
      - How can I tell if a catalog is currently enabled?
      instructions:
      - text: Show the enabled or disabled status of catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Find out who last changed the status of catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/status'].patch
  update:
    x-apievangelist-phrasing:
      intent: Disable or re-enable a catalog
      effect: write
      questions:
      - Can I temporarily disable a catalog and turn it back on later?
      - What's the way to mark a catalog as disabled?
      instructions:
      - text: Set catalog {catalog_hrn} disabled to {disabled}.
        slots:
          catalog_hrn: path.catalogHrn
          disabled: requestBody.disabled
      - text: Re-enable the disabled catalog {catalog_hrn} by setting disabled to {disabled}.
        slots:
          catalog_hrn: path.catalogHrn
          disabled: requestBody.disabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/layers/{layerId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a layer from a catalog
      effect: destructive
      questions:
      - How do I remove a single layer from a catalog without deleting the catalog?
      - Can I drop one layer I no longer use?
      instructions:
      - text: Delete layer {layer_id} from catalog {catalog_hrn}.
        slots:
          layer_id: path.layerId
          catalog_hrn: path.catalogHrn
      - text: Remove the {layer_id} layer in catalog {catalog_hrn}.
        slots:
          layer_id: path.layerId
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/layers/{layerId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Modify a catalog layer's settings
      effect: write
      questions:
      - Can I change the TTL or tags on an existing layer?
      - How do I update a layer's summary and description only?
      instructions:
      - text: Set the TTL of layer {layer_id} in catalog {catalog_hrn} to {ttl}.
        slots:
          layer_id: path.layerId
          catalog_hrn: path.catalogHrn
          ttl: requestBody.ttl
      - text: Change the description of layer {layer_id} in catalog {catalog_hrn} to {description}.
        slots:
          layer_id: path.layerId
          catalog_hrn: path.catalogHrn
          description: requestBody.description
      - text: Update the tags on layer {layer_id} of catalog {catalog_hrn} to {tags}.
        slots:
          layer_id: path.layerId
          catalog_hrn: path.catalogHrn
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/subsets'].get
  update:
    x-apievangelist-phrasing:
      intent: List subsets with the deprecated endpoint
      effect: read
      questions:
      - Which subsets containing a given area can I access using the old subsets endpoint?
      - Is the legacy subsets listing still available?
      instructions:
      - text: List subsets of catalog {catalog_hrn} for areas {areas} using the deprecated subsets endpoint.
        slots:
          catalog_hrn: path.catalogHrn
          areas: query.areas
      - text: Show all legacy subsets I can access in catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/subsets/{subsetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one subset via the deprecated endpoint
      effect: read
      questions:
      - Can I still read a single subset through the old subsets route?
      - How do I look up a legacy subset by its ID?
      instructions:
      - text: Get legacy subset {subset_id} in catalog {catalog_hrn}.
        slots:
          subset_id: path.subsetId
          catalog_hrn: path.catalogHrn
      - text: Show the details of old-style subset {subset_id} from catalog {catalog_hrn}.
        slots:
          subset_id: path.subsetId
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/subsetsFingerprint'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the legacy subsets fingerprint
      effect: read
      questions:
      - Is there a fingerprint of my accessible subsets on the deprecated endpoint?
      - What does the old subsets fingerprint represent?
      instructions:
      - text: Get the legacy subsets fingerprint for catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Fetch my deprecated subset configuration fingerprint in catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/dataSubsets'].get
  update:
    x-apievangelist-phrasing:
      intent: List accessible data subsets
      effect: read
      questions:
      - Which data subsets can I access for a given area or layer?
      - Can I filter data subsets by layer IDs?
      instructions:
      - text: List data subsets in catalog {catalog_hrn} covering areas {areas}.
        slots:
          catalog_hrn: path.catalogHrn
          areas: query.areas
      - text: Show data subsets of catalog {catalog_hrn} for layers {layers}.
        slots:
          catalog_hrn: path.catalogHrn
          layers: query.layers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/dataSubsets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create data subsets in a catalog
      effect: write
      questions:
      - How many data subsets can I create in one request?
      - Is creating data subsets asynchronous with a status link?
      instructions:
      - text: Create new data subsets in catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Add a batch of data subsets to catalog {catalog_hrn} and return the status link.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/dataSubsets/{dataSubsetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one data subset
      effect: read
      questions:
      - How do I see the details of one data subset?
      - What is defined in a specific data subset of my catalog?
      instructions:
      - text: Get data subset {data_subset_id} in catalog {catalog_hrn}.
        slots:
          data_subset_id: path.dataSubsetId
          catalog_hrn: path.catalogHrn
      - text: Show the configuration of data subset {data_subset_id} from catalog {catalog_hrn}.
        slots:
          data_subset_id: path.dataSubsetId
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/dataSubsets/{dataSubsetId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a data subset
      effect: destructive
      questions:
      - Can I delete one data subset and track the deletion status?
      - What's returned when a data subset is removed?
      instructions:
      - text: Delete data subset {data_subset_id} from catalog {catalog_hrn}.
        slots:
          data_subset_id: path.dataSubsetId
          catalog_hrn: path.catalogHrn
      - text: Remove the data subset {data_subset_id} in catalog {catalog_hrn} and give me the status link.
        slots:
          data_subset_id: path.dataSubsetId
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/dataSubsetsFingerprint'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the data subsets fingerprint
      effect: read
      questions:
      - Can I detect when my accessible data subset configuration has changed?
      - What is a data subsets fingerprint used for?
      instructions:
      - text: Get the data subsets fingerprint for catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Fetch the fingerprint of my accessible data subsets in catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/catalogs/{catalogHrn}/automaticVersionDeletion'].delete
  update:
    x-apievangelist-phrasing:
      intent: Turn off automatic version deletion
      effect: destructive
      questions:
      - How do I stop retired catalog versions from being cleaned up automatically?
      - Can I disable automatic version deletion on a catalog?
      instructions:
      - text: Disable automatic version deletion for catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      - text: Stop the automatic cleanup of retired versions in catalog {catalog_hrn}.
        slots:
          catalog_hrn: path.catalogHrn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/status/{token}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a catalog create, update or delete request
      effect: read
      questions:
      - How do I track whether my catalog creation finished?
      - Where can I check progress of a catalog delete I submitted?
      instructions:
      - text: Check the status of catalog request token {token}.
        slots:
          token: path.token
      - text: Tell me if the catalog operation with token {token} has completed.
        slots:
          token: path.token
      method: generated
      generated: '2026-09-26'