# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Azure Digital Twins API
  version: 1.0.0
extends: openapi/microsoft-azure-twins-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: 14
- target: $.paths['/digitaltwins/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a digital twin
      effect: read
      questions:
      - How do I fetch the current state of one digital twin by its id?
      - What happens if the digital twin I ask for doesn't exist?
      instructions:
      - text: Get digital twin {id}.
        slots:
          id: path.id
      - text: Show me the properties of twin {id} in Azure Digital Twins.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a digital twin
      effect: write
      questions:
      - Can I create a digital twin only if it doesn't already exist?
      - Why would adding a twin fail because its model is decommissioned or the twin limit is reached?
      instructions:
      - text: Create digital twin {id}.
        slots:
          id: path.id
      - text: Replace digital twin {id} with a new payload.
        slots:
          id: path.id
      - text: Add twin {id} only if none exists, using If-None-Match {ifNoneMatch}.
        slots:
          id: path.id
          ifNoneMatch: header.If-None-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a digital twin
      effect: destructive
      questions:
      - Do I have to delete a twin's relationships before deleting the twin itself?
      - Can I delete a digital twin only when its ETag still matches?
      instructions:
      - text: Delete digital twin {id}.
        slots:
          id: path.id
      - text: Delete twin {id} if its ETag is still {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a digital twin's properties
      effect: write
      questions:
      - How do I change a few properties on a twin with a JSON Patch?
      - What makes a JSON Patch on a digital twin fail validation?
      instructions:
      - text: Apply a JSON Patch to digital twin {id}.
        slots:
          id: path.id
      - text: Update twin {id} properties only if its ETag matches {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/relationships/{relationshipId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a relationship between two twins
      effect: read
      questions:
      - How do I read one specific relationship on a digital twin?
      - Can I look up a twin relationship by its relationship id?
      instructions:
      - text: Get relationship {relationshipId} on digital twin {id}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
      - text: Show the relationship {relationshipId} from twin {id}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/relationships/{relationshipId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a relationship between two twins
      effect: write
      questions:
      - How do I connect two digital twins with a relationship?
      - Why would a new twin relationship be rejected as invalid?
      instructions:
      - text: Create relationship {relationshipId} from twin {id}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
      - text: Add relationship {relationshipId} on twin {id} only if it doesn't exist yet, If-None-Match {ifNoneMatch}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
          ifNoneMatch: header.If-None-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/relationships/{relationshipId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a relationship between two twins
      effect: destructive
      questions:
      - Can I remove a link between two digital twins without deleting either twin?
      - Is there an ETag check when deleting a twin relationship?
      instructions:
      - text: Delete relationship {relationshipId} from digital twin {id}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
      - text: Remove relationship {relationshipId} on twin {id} if its ETag is {ifMatch}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/relationships/{relationshipId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update properties on a twin relationship
      effect: write
      questions:
      - Can I change the properties on an existing relationship between twins?
      - How do I patch a relationship rather than recreating it?
      instructions:
      - text: Patch the properties of relationship {relationshipId} on twin {id}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
      - text: Update relationship {relationshipId} of twin {id} only if its ETag matches {ifMatch}.
        slots:
          relationshipId: path.relationshipId
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/relationships'].get
  update:
    x-apievangelist-phrasing:
      intent: List a twin's outgoing relationships
      effect: read
      questions:
      - Which twins does a given digital twin point to?
      - Can I list only relationships with a particular name, like 'contains'?
      instructions:
      - text: List the outgoing relationships of digital twin {id}.
        slots:
          id: path.id
      - text: List relationships named {relationshipName} from twin {id}.
        slots:
          relationshipName: query.relationshipName
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/incomingrelationships'].get
  update:
    x-apievangelist-phrasing:
      intent: List a twin's incoming relationships
      effect: read
      questions:
      - Which other twins have relationships pointing at this twin?
      - How do I find everything that references a digital twin before deleting it?
      instructions:
      - text: List incoming relationships for digital twin {id}.
        slots:
          id: path.id
      - text: Show which twins point to twin {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/telemetry'].post
  update:
    x-apievangelist-phrasing:
      intent: Send telemetry for a digital twin
      effect: write
      questions:
      - How do I publish telemetry on behalf of a digital twin?
      - Is a message id required when sending twin telemetry?
      instructions:
      - text: Send telemetry for twin {id} with message id {messageId}.
        slots:
          id: path.id
          messageId: header.Message-Id
      - text: Publish telemetry from twin {id} as message {messageId} with source time {sourceTime}.
        slots:
          id: path.id
          messageId: header.Message-Id
          sourceTime: header.Telemetry-Source-Time
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/components/{componentPath}/telemetry'].post
  update:
    x-apievangelist-phrasing:
      intent: Send telemetry for a twin component
      effect: write
      questions:
      - Can I send telemetry for a single component of a twin instead of the whole twin?
      - What does a component path look like when sending component telemetry?
      instructions:
      - text: Send telemetry for component {componentPath} of twin {id} with message id {messageId}.
        slots:
          componentPath: path.componentPath
          id: path.id
          messageId: header.Message-Id
      - text: Publish component {componentPath} telemetry on twin {id} as message {messageId}.
        slots:
          componentPath: path.componentPath
          id: path.id
          messageId: header.Message-Id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/components/{componentPath}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a component of a digital twin
      effect: read
      questions:
      - How do I read just one component from a digital twin?
      - What error comes back if the component path isn't on the twin?
      instructions:
      - text: Get component {componentPath} of digital twin {id}.
        slots:
          componentPath: path.componentPath
          id: path.id
      - text: Show the current values of component {componentPath} on twin {id}.
        slots:
          componentPath: path.componentPath
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/digitaltwins/{id}/components/{componentPath}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a component on a digital twin
      effect: write
      questions:
      - Can I patch the properties of a single twin component?
      - Is there optimistic concurrency when updating a twin component?
      instructions:
      - text: Apply a JSON Patch to component {componentPath} of twin {id}.
        slots:
          componentPath: path.componentPath
          id: path.id
      - text: Update component {componentPath} on twin {id} only if ETag is {ifMatch}.
        slots:
          componentPath: path.componentPath
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'