# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Interactive Map API v1 Write Features API
  version: 1.0.0
extends: openapi/here-write-features-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: 6
- target: $.paths['/layers/{layerId}/features'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace many map features
      effect: write
      questions:
      - How do I upload a GeoJSON FeatureCollection into an interactive map layer, replacing any existing features with the same IDs?
      - Can I bulk-write features against a specific layer version?
      instructions:
      - text: Create or replace the features {features} in layer {layerId}.
        slots:
          features: requestBody.features
          layerId: path.layerId
      - text: Overwrite layer {layerId} features with this FeatureCollection {features} at version {versionRef}.
        slots:
          layerId: path.layerId
          features: requestBody.features
          versionRef: query.versionRef
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/features'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or patch many features
      effect: write
      questions:
      - How do I merge changes into several features at once instead of replacing them?
      - Can I send a list of feature modifications to an interactive map layer?
      instructions:
      - text: Patch features {features} in layer {layerId}, creating any that are missing.
        slots:
          features: requestBody.features
          layerId: path.layerId
      - text: Apply the feature modifications {modifications} to layer {layerId}.
        slots:
          modifications: requestBody.modifications
          layerId: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/features'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several features or wipe a layer
      effect: destructive
      questions:
      - How do I delete a list of features by ID from a map layer?
      - Can I erase all content in an interactive map layer at once?
      instructions:
      - text: Delete features {id} from layer {layerId}.
        slots:
          id: query.id
          layerId: path.layerId
      - text: Erase all content in layer {layerId} with eraseContent {eraseContent}.
        slots:
          layerId: path.layerId
          eraseContent: query.eraseContent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/features/{featureId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a single feature
      effect: write
      questions:
      - How do I write one feature with a known ID into a layer, replacing it entirely if it exists?
      - Can I set a single feature's geometry and properties in one call?
      instructions:
      - text: Create or replace feature {featureId} in layer {layerId}.
        slots:
          featureId: path.featureId
          layerId: path.layerId
      - text: Replace feature {featureId} on {layerId} with geometry {geometry} and properties {properties}.
        slots:
          featureId: path.featureId
          layerId: path.layerId
          geometry: requestBody.geometry
          properties: requestBody.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/features/{featureId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one feature
      effect: destructive
      questions:
      - How do I remove a single feature from a map layer?
      - Can I delete a feature at a particular layer version?
      instructions:
      - text: Delete feature {featureId} from layer {layerId}.
        slots:
          featureId: path.featureId
          layerId: path.layerId
      - text: Remove the single feature {featureId} in {layerId} at version {versionRef}.
        slots:
          featureId: path.featureId
          layerId: path.layerId
          versionRef: query.versionRef
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/features/{featureId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update one feature
      effect: write
      questions:
      - How do I change just some properties of an existing feature without resending all of it?
      - Can I patch the geometry of one feature already in a layer?
      instructions:
      - text: Patch feature {featureId} in layer {layerId} with properties {properties}.
        slots:
          featureId: path.featureId
          layerId: path.layerId
          properties: requestBody.properties
      - text: Update only the geometry of existing feature {featureId} on {layerId} to {geometry}.
        slots:
          featureId: path.featureId
          layerId: path.layerId
          geometry: requestBody.geometry
      method: generated
      generated: '2026-09-26'