Microsoft Azure Azure Digital Twins API — Twins

naftiko: 1.0.0-alpha2
info:
  label: Microsoft Azure Azure Digital Twins API — Twins
  description: 'Microsoft Azure Azure Digital Twins API — Twins. 14 operations. Lead operation: Microsoft Azure Get Digitaltwins
    Id. Self-contained Naftiko capability covering one Microsoft Azure business surface.'
  tags:
  - Microsoft Azure
  - Twins
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    MICROSOFT_AZURE_API_KEY: MICROSOFT_AZURE_API_KEY
capability:
  consumes:
  - type: http
    namespace: azure-digital-twins-twins
    baseUri: https://digitaltwins-hostname
    description: Microsoft Azure Azure Digital Twins API — Twins business capability. Self-contained, no shared references.
    resources:
    - name: digitaltwins-id
      path: /digitaltwins/{id}
      operations:
      - name: microsoftazuredigitaltwinsgetbyid
        method: GET
        description: Microsoft Azure Get Digitaltwins Id
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: microsoftazuredigitaltwinsadd
        method: PUT
        description: Microsoft Azure Put Digitaltwins Id
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: twin
          in: body
          type: object
          description: The digital twin instance being added. If provided, the $dtId property is ignored.
          required: true
      - name: microsoftazuredigitaltwinsdelete
        method: DELETE
        description: Microsoft Azure Delete Digitaltwins Id
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: microsoftazuredigitaltwinsupdate
        method: PATCH
        description: Microsoft Azure Patch Digitaltwins Id
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: patchDocument
          in: body
          type: array
          description: An update specification described by JSON Patch. Updates to property values and $model elements may
            happen in the same request. Operations are limited to add, r
          required: true
    - name: digitaltwins-id-components-componentPath
      path: /digitaltwins/{id}/components/{componentPath}
      operations:
      - name: microsoftazuredigitaltwinsgetcomponent
        method: GET
        description: Microsoft Azure Get Digitaltwins Id Components Componentpath
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: microsoftazuredigitaltwinsupdatecomponent
        method: PATCH
        description: Microsoft Azure Patch Digitaltwins Id Components Componentpath
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: patchDocument
          in: body
          type: array
          description: An update specification described by JSON Patch. Updates to property values and $model elements may
            happen in the same request. Operations are limited to add, r
          required: true
    - name: digitaltwins-id-components-componentPath-telemetry
      path: /digitaltwins/{id}/components/{componentPath}/telemetry
      operations:
      - name: microsoftazuredigitaltwinssendcomponenttelemetry
        method: POST
        description: Microsoft Azure Post Digitaltwins Id Components Componentpath Telemetry
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: telemetry
          in: body
          type: object
          description: The telemetry measurements to send from the digital twin's component.
          required: true
        - name: Message-Id
          in: header
          type: string
          description: A unique message identifier (in the scope of the digital twin id) that is commonly used for de-duplicating
            messages.
          required: true
        - name: Telemetry-Source-Time
          in: header
          type: string
          description: An RFC 3339 timestamp that identifies the time the telemetry was measured.
    - name: digitaltwins-id-incomingrelationships
      path: /digitaltwins/{id}/incomingrelationships
      operations:
      - name: microsoftazuredigitaltwinslistincomingrelationships
        method: GET
        description: Microsoft Azure Get Digitaltwins Id Incomingrelationships
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: digitaltwins-id-relationships
      path: /digitaltwins/{id}/relationships
      operations:
      - name: microsoftazuredigitaltwinslistrelationships
        method: GET
        description: Microsoft Azure Get Digitaltwins Id Relationships
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: relationshipName
          in: query
          type: string
          description: The name of the relationship.
    - name: digitaltwins-id-relationships-relationshipId
      path: /digitaltwins/{id}/relationships/{relationshipId}
      operations:
      - name: microsoftazuredigitaltwinsgetrelationshipbyid
        method: GET
        description: Microsoft Azure Get Digitaltwins Id Relationships Relationshipid
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: microsoftazuredigitaltwinsaddrelationship
        method: PUT
        description: Microsoft Azure Put Digitaltwins Id Relationships Relationshipid
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: relationship
          in: body
          type: object
          description: The data for the relationship.
          required: true
      - name: microsoftazuredigitaltwinsdeleterelationship
        method: DELETE
        description: Microsoft Azure Delete Digitaltwins Id Relationships Relationshipid
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: microsoftazuredigitaltwinsupdaterelationship
        method: PATCH
        description: Microsoft Azure Patch Digitaltwins Id Relationships Relationshipid
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: patchDocument
          in: body
          type: array
          description: JSON Patch description of the update to the relationship properties.
          required: true
    - name: digitaltwins-id-telemetry
      path: /digitaltwins/{id}/telemetry
      operations:
      - name: microsoftazuredigitaltwinssendtelemetry
        method: POST
        description: Microsoft Azure Post Digitaltwins Id Telemetry
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: telemetry
          in: body
          type: object
          description: The telemetry measurements to send from the digital twin.
          required: true
        - name: Message-Id
          in: header
          type: string
          description: A unique message identifier (in the scope of the digital twin id) that is commonly used for de-duplicating
            messages.
          required: true
        - name: Telemetry-Source-Time
          in: header
          type: string
          description: An RFC 3339 timestamp that identifies the time the telemetry was measured.
  exposes:
  - type: rest
    namespace: azure-digital-twins-twins-rest
    port: 8080
    description: REST adapter for Microsoft Azure Azure Digital Twins API — Twins. One Spectral-compliant resource per consumed
      operation, prefixed with /v1.
    resources:
    - path: /v1/digitaltwins/{id}
      name: digitaltwins-id
      description: REST surface for digitaltwins-id.
      operations:
      - method: GET
        name: microsoftazuredigitaltwinsgetbyid
        description: Microsoft Azure Get Digitaltwins Id
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsgetbyid
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: microsoftazuredigitaltwinsadd
        description: Microsoft Azure Put Digitaltwins Id
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsadd
        with:
          twin: rest.twin
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: microsoftazuredigitaltwinsdelete
        description: Microsoft Azure Delete Digitaltwins Id
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsdelete
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: microsoftazuredigitaltwinsupdate
        description: Microsoft Azure Patch Digitaltwins Id
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsupdate
        with:
          patchDocument: rest.patchDocument
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/digitaltwins/{id}/components/{componentpath}
      name: digitaltwins-id-components-componentpath
      description: REST surface for digitaltwins-id-components-componentPath.
      operations:
      - method: GET
        name: microsoftazuredigitaltwinsgetcomponent
        description: Microsoft Azure Get Digitaltwins Id Components Componentpath
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsgetcomponent
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: microsoftazuredigitaltwinsupdatecomponent
        description: Microsoft Azure Patch Digitaltwins Id Components Componentpath
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsupdatecomponent
        with:
          patchDocument: rest.patchDocument
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/digitaltwins/{id}/components/{componentpath}/telemetry
      name: digitaltwins-id-components-componentpath-telemetry
      description: REST surface for digitaltwins-id-components-componentPath-telemetry.
      operations:
      - method: POST
        name: microsoftazuredigitaltwinssendcomponenttelemetry
        description: Microsoft Azure Post Digitaltwins Id Components Componentpath Telemetry
        call: azure-digital-twins-twins.microsoftazuredigitaltwinssendcomponenttelemetry
        with:
          telemetry: rest.telemetry
          Message-Id: rest.Message-Id
          Telemetry-Source-Time: rest.Telemetry-Source-Time
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/digitaltwins/{id}/incomingrelationships
      name: digitaltwins-id-incomingrelationships
      description: REST surface for digitaltwins-id-incomingrelationships.
      operations:
      - method: GET
        name: microsoftazuredigitaltwinslistincomingrelationships
        description: Microsoft Azure Get Digitaltwins Id Incomingrelationships
        call: azure-digital-twins-twins.microsoftazuredigitaltwinslistincomingrelationships
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/digitaltwins/{id}/relationships
      name: digitaltwins-id-relationships
      description: REST surface for digitaltwins-id-relationships.
      operations:
      - method: GET
        name: microsoftazuredigitaltwinslistrelationships
        description: Microsoft Azure Get Digitaltwins Id Relationships
        call: azure-digital-twins-twins.microsoftazuredigitaltwinslistrelationships
        with:
          relationshipName: rest.relationshipName
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/digitaltwins/{id}/relationships/{relationshipid}
      name: digitaltwins-id-relationships-relationshipid
      description: REST surface for digitaltwins-id-relationships-relationshipId.
      operations:
      - method: GET
        name: microsoftazuredigitaltwinsgetrelationshipbyid
        description: Microsoft Azure Get Digitaltwins Id Relationships Relationshipid
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsgetrelationshipbyid
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: microsoftazuredigitaltwinsaddrelationship
        description: Microsoft Azure Put Digitaltwins Id Relationships Relationshipid
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsaddrelationship
        with:
          relationship: rest.relationship
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: microsoftazuredigitaltwinsdeleterelationship
        description: Microsoft Azure Delete Digitaltwins Id Relationships Relationshipid
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsdeleterelationship
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: microsoftazuredigitaltwinsupdaterelationship
        description: Microsoft Azure Patch Digitaltwins Id Relationships Relationshipid
        call: azure-digital-twins-twins.microsoftazuredigitaltwinsupdaterelationship
        with:
          patchDocument: rest.patchDocument
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/digitaltwins/{id}/telemetry
      name: digitaltwins-id-telemetry
      description: REST surface for digitaltwins-id-telemetry.
      operations:
      - method: POST
        name: microsoftazuredigitaltwinssendtelemetry
        description: Microsoft Azure Post Digitaltwins Id Telemetry
        call: azure-digital-twins-twins.microsoftazuredigitaltwinssendtelemetry
        with:
          telemetry: rest.telemetry
          Message-Id: rest.Message-Id
          Telemetry-Source-Time: rest.Telemetry-Source-Time
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: azure-digital-twins-twins-mcp
    port: 9090
    transport: http
    description: MCP adapter for Microsoft Azure Azure Digital Twins API — Twins. One tool per consumed operation, routed
      inline through this capability's consumes block.
    tools:
    - name: microsoft-azure-get-digitaltwins-id
      description: Microsoft Azure Get Digitaltwins Id
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsgetbyid
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-put-digitaltwins-id
      description: Microsoft Azure Put Digitaltwins Id
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsadd
      with:
        twin: tools.twin
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-delete-digitaltwins-id
      description: Microsoft Azure Delete Digitaltwins Id
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsdelete
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-patch-digitaltwins-id
      description: Microsoft Azure Patch Digitaltwins Id
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsupdate
      with:
        patchDocument: tools.patchDocument
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-get-digitaltwins-id-2
      description: Microsoft Azure Get Digitaltwins Id Components Componentpath
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsgetcomponent
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-patch-digitaltwins-id-2
      description: Microsoft Azure Patch Digitaltwins Id Components Componentpath
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsupdatecomponent
      with:
        patchDocument: tools.patchDocument
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-post-digitaltwins-id
      description: Microsoft Azure Post Digitaltwins Id Components Componentpath Telemetry
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: azure-digital-twins-twins.microsoftazuredigitaltwinssendcomponenttelemetry
      with:
        telemetry: tools.telemetry
        Message-Id: tools.Message-Id
        Telemetry-Source-Time: tools.Telemetry-Source-Time
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-get-digitaltwins-id-3
      description: Microsoft Azure Get Digitaltwins Id Incomingrelationships
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinslistincomingrelationships
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-get-digitaltwins-id-4
      description: Microsoft Azure Get Digitaltwins Id Relationships
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinslistrelationships
      with:
        relationshipName: tools.relationshipName
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-get-digitaltwins-id-5
      description: Microsoft Azure Get Digitaltwins Id Relationships Relationshipid
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsgetrelationshipbyid
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-put-digitaltwins-id-2
      description: Microsoft Azure Put Digitaltwins Id Relationships Relationshipid
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsaddrelationship
      with:
        relationship: tools.relationship
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-delete-digitaltwins-id-2
      description: Microsoft Azure Delete Digitaltwins Id Relationships Relationshipid
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsdeleterelationship
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-patch-digitaltwins-id-3
      description: Microsoft Azure Patch Digitaltwins Id Relationships Relationshipid
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: azure-digital-twins-twins.microsoftazuredigitaltwinsupdaterelationship
      with:
        patchDocument: tools.patchDocument
      outputParameters:
      - type: object
        mapping: $.
    - name: microsoft-azure-post-digitaltwins-id-2
      description: Microsoft Azure Post Digitaltwins Id Telemetry
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: azure-digital-twins-twins.microsoftazuredigitaltwinssendtelemetry
      with:
        telemetry: tools.telemetry
        Message-Id: tools.Message-Id
        Telemetry-Source-Time: tools.Telemetry-Source-Time
      outputParameters:
      - type: object
        mapping: $.