# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Adobe Suite Datasets API
  version: 1.0.0
extends: openapi/adobe-suite-datasets-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: 10
- target: $.paths['/dataSets'].get
  update:
    x-apievangelist-phrasing:
      intent: List datasets in a sandbox
      effect: read
      questions:
      - How do I see all the datasets in my Experience Platform sandbox?
      - Can I filter the dataset list by name or tags?
      - What's the maximum number of datasets returned per page, and how do I page further?
      instructions:
      - text: List the datasets in sandbox {sandbox}.
        slots:
          sandbox: header.x-sandbox-name
      - text: List datasets named {name}, limited to {limit} results.
        slots:
          name: query.name
          limit: query.limit
      - text: List datasets tagged {tags}, sorted by {orderBy}.
        slots:
          tags: query.tags
          orderBy: query.orderBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dataSets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a dataset
      effect: write
      questions:
      - How do I create a new dataset tied to an XDM schema?
      - Can I turn on error diagnostics when creating a dataset?
      instructions:
      - text: Create a dataset named {name} using schema {schemaRef}.
        slots:
          name: requestBody.name
          schemaRef: requestBody.schemaRef
      - text: Create dataset {name} in sandbox {sandbox} with error diagnostics {enableErrorDiagnostics}.
        slots:
          name: requestBody.name
          sandbox: header.x-sandbox-name
          enableErrorDiagnostics: requestBody.enableErrorDiagnostics
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dataSets/{DATASET_ID}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a dataset
      effect: read
      questions:
      - How do I get the details of one dataset by its ID?
      - Can I return only selected properties of a dataset?
      instructions:
      - text: Look up dataset {DATASET_ID}.
        slots:
          DATASET_ID: path.DATASET_ID
      - text: Get dataset {DATASET_ID} returning only {properties}.
        slots:
          DATASET_ID: path.DATASET_ID
          properties: query.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dataSets/{DATASET_ID}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a dataset's definition
      effect: write
      questions:
      - Can I overwrite a dataset's full definition with a new one?
      - Can I replace a dataset's name, description and schema in one full update?
      instructions:
      - text: Replace the definition of dataset {DATASET_ID} with name {name} and description {description}.
        slots:
          DATASET_ID: path.DATASET_ID
          name: requestBody.name
          description: requestBody.description
      - text: Do a full PUT update of dataset {DATASET_ID} pointing it at schema {schemaRef}.
        slots:
          DATASET_ID: path.DATASET_ID
          schemaRef: requestBody.schemaRef
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dataSets/{DATASET_ID}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a dataset
      effect: destructive
      questions:
      - What's the way to delete a dataset I no longer need?
      - Can I remove a dataset from a specific sandbox?
      instructions:
      - text: Delete dataset {DATASET_ID}.
        slots:
          DATASET_ID: path.DATASET_ID
      - text: Delete dataset {DATASET_ID} from sandbox {sandbox}.
        slots:
          DATASET_ID: path.DATASET_ID
          sandbox: header.x-sandbox-name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dataSets/{DATASET_ID}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change specific fields of a dataset
      effect: write
      questions:
      - Can I change just a dataset's tags without resending the whole thing?
      - What's the way to partially update a dataset's attributes?
      instructions:
      - text: Patch dataset {DATASET_ID} to set its tags to {tags}.
        slots:
          DATASET_ID: path.DATASET_ID
          tags: requestBody.tags
      - text: Rename dataset {DATASET_ID} to {name}, leaving other attributes as they are.
        slots:
          DATASET_ID: path.DATASET_ID
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dataSets/{id}/credentials'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dataset's access credentials
      effect: read
      questions:
      - How do I get the storage credentials for reading or writing a dataset's files?
      - Can I request dataset credentials scoped to a batch I'm writing?
      instructions:
      - text: Get credentials for dataset {id}.
        slots:
          id: path.id
      - text: Fetch write credentials for dataset {id} for batch {batchId}.
        slots:
          id: path.id
          batchId: query.batchId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{DATASET_ID}/labels'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a dataset's data usage labels
      effect: read
      questions:
      - Which data usage labels are applied to a dataset?
      - Where can I check the governance labels on a dataset's fields?
      instructions:
      - text: Get the data usage labels for dataset {DATASET_ID}.
        slots:
          DATASET_ID: path.DATASET_ID
      - text: Show governance labels on dataset {DATASET_ID} in sandbox {sandbox}.
        slots:
          DATASET_ID: path.DATASET_ID
          sandbox: header.x-sandbox-name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{DATASET_ID}/labels'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a dataset's data usage labels
      effect: write
      questions:
      - How do I change the data usage labels on a dataset that already has labels?
      - Can I remove all labels from a dataset by sending an empty list?
      instructions:
      - text: Set the data usage labels on dataset {DATASET_ID} to {labels}, matching version {If-Match}.
        slots:
          DATASET_ID: path.DATASET_ID
          labels: requestBody.labels
          If-Match: header.If-Match
      - text: Update field-level labels on dataset {DATASET_ID} to {optionalLabels} using version {If-Match}.
        slots:
          DATASET_ID: path.DATASET_ID
          optionalLabels: requestBody.optionalLabels
          If-Match: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{DATASET_ID}/labels'].post
  update:
    x-apievangelist-phrasing:
      intent: Add labels to a dataset (deprecated)
      effect: write
      questions:
      - Is there a deprecated POST call for adding first-time labels to a dataset?
      - Can I still use the old add-labels endpoint to label dataset fields?
      instructions:
      - text: Use the deprecated add-labels call to apply {labels} to dataset {DATASET_ID}.
        slots:
          labels: requestBody.labels
          DATASET_ID: path.DATASET_ID
      - text: Add field labels {optionalLabels} to dataset {DATASET_ID} with the legacy POST endpoint.
        slots:
          optionalLabels: requestBody.optionalLabels
          DATASET_ID: path.DATASET_ID
      method: generated
      generated: '2026-09-26'