# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for v1 Blob API
  version: 1.0.0
extends: openapi/here-blob-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: 9
- target: $.paths['/layers/{layerId}/data/{dataHandle}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a blob by data handle
      effect: read
      questions:
      - How do I download a partition's data blob using its data handle?
      - Can I skip re-downloading a data handle blob if it has not changed?
      instructions:
      - text: Download data handle {dataHandle} from layer {layerId}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Fetch blob {dataHandle} in {layerId} only if it differs from ETag {If-None-Match}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
          If-None-Match: header.If-None-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/data/{dataHandle}'].put
  update:
    x-apievangelist-phrasing:
      intent: Publish a volatile data blob
      effect: write
      questions:
      - How do I write or overwrite data in a volatile layer?
      - Can I send a digest so the server verifies a volatile blob upload?
      instructions:
      - text: Publish data to handle {dataHandle} in volatile layer {layerId}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Upload a volatile blob to {dataHandle} in {layerId} as {contentType} with digest {digest}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
          contentType: header.Content-Type
          digest: header.X-HERE-Digest
      method: generated
      generated: '2026-10-01'
- target: $.paths['/layers/{layerId}/data/{dataHandle}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a blob from an index layer
      effect: destructive
      questions:
      - How do I delete a data blob from an index layer?
      - Can I delete data handle blobs from layers that are not index layers?
      instructions:
      - text: Delete data handle {dataHandle} from index layer {layerId}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Remove blob {dataHandle} stored in index layer {layerId}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/data/{dataHandle}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check that a data handle exists
      effect: read
      questions:
      - How can I tell whether a data handle already has a blob before uploading?
      - Is there a lightweight existence check for a data handle?
      instructions:
      - text: Check whether data handle {dataHandle} exists in layer {layerId}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Verify blob {dataHandle} is present on {layerId}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/data/{dataHandle}/multiparts'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a multipart upload for a data handle
      effect: write
      questions:
      - How do I upload a very large blob to a data handle in parts?
      - Where do I get the URLs for the later multipart steps of a data handle upload?
      instructions:
      - text: Start a multipart upload for data handle {dataHandle} in layer {layerId} as {contentType}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
          contentType: requestBody.contentType
      - text: Begin uploading blob {dataHandle} to {layerId} in multiple parts.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/data/{dataHandle}/multiparts/{multiPartToken}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a data handle upload's status
      effect: read
      questions:
      - Has the multipart upload for my data handle finished?
      - Can I see the status of a data handle multipart upload before it completes?
      instructions:
      - text: Get the status of upload {multiPartToken} for data handle {dataHandle} in {layerId}.
        slots:
          multiPartToken: path.multiPartToken
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Tell me whether multipart {multiPartToken} of blob {dataHandle} on {layerId} is done.
        slots:
          multiPartToken: path.multiPartToken
          dataHandle: path.dataHandle
          layerId: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/data/{dataHandle}/multiparts/{multiPartToken}'].put
  update:
    x-apievangelist-phrasing:
      intent: Finish a data handle multipart upload
      effect: write
      questions:
      - How do I finalize a data handle upload once all its parts are sent?
      - What happens after the last part of a data handle blob is uploaded?
      instructions:
      - text: Complete upload {multiPartToken} for data handle {dataHandle} in {layerId}.
        slots:
          multiPartToken: path.multiPartToken
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Finalize blob {dataHandle} on {layerId} from parts {parts} of upload {multiPartToken}.
        slots:
          dataHandle: path.dataHandle
          layerId: path.layerId
          parts: requestBody.parts
          multiPartToken: path.multiPartToken
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/data/{dataHandle}/multiparts/{multiPartToken}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a data handle multipart upload
      effect: destructive
      questions:
      - How do I abort a partly finished upload for a data handle?
      - Can I cancel a data handle multipart upload that already completed?
      instructions:
      - text: Cancel upload {multiPartToken} for data handle {dataHandle} in {layerId}.
        slots:
          multiPartToken: path.multiPartToken
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Abort multipart {multiPartToken} of blob {dataHandle} on layer {layerId}.
        slots:
          multiPartToken: path.multiPartToken
          dataHandle: path.dataHandle
          layerId: path.layerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/layers/{layerId}/data/{dataHandle}/multiparts/{multiPartToken}/parts'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload one part of a data handle blob
      effect: write
      questions:
      - What is the minimum part size for a data handle multipart upload?
      - How are the parts of a data handle upload numbered?
      instructions:
      - text: Upload part {partNumber} of upload {multiPartToken} for data handle {dataHandle} in {layerId}.
        slots:
          partNumber: query.partNumber
          multiPartToken: path.multiPartToken
          dataHandle: path.dataHandle
          layerId: path.layerId
      - text: Send part {partNumber} ({Content-Length} bytes) of blob {dataHandle} on {layerId}, upload {multiPartToken}.
        slots:
          partNumber: query.partNumber
          Content-Length: header.Content-Length
          dataHandle: path.dataHandle
          layerId: path.layerId
          multiPartToken: path.multiPartToken
      method: generated
      generated: '2026-09-26'