Microsoft Azure Twins API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Twins API
schemes:
- https
tags:
- name: Twins
paths:
  /digitaltwins/{id}:
    parameters:
    - $ref: '#/parameters/traceparent'
    - $ref: '#/parameters/tracestate'
    get:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsGetbyid
      description: Retrieves a digital twin.<br>Status codes:<br>* 200 OK<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.
      x-ms-examples:
        Get a digital twin by id:
          $ref: ./examples/GetTwin.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DigitalTwin'
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Digitaltwins Id
    put:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsAdd
      description: Adds or replaces a digital twin.<br>Status codes:<br>* 200 OK<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id or payload is invalid.<br>  * ModelDecommissioned - The model for the digital twin is decommissioned.<br>  * TwinLimitReached - The maximum number of digital twins allowed has been reached.<br>  * ValidationFailed - The digital twin payload is not valid.<br>* 412 Precondition Failed<br>  * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
      x-ms-examples:
        Add a digital twin:
          $ref: ./examples/PutTwinBasicExample.json
        Add a digital twin (with properties and components):
          $ref: ./examples/PutTwinAdvancedExample.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - name: twin
        description: The digital twin instance being added. If provided, the $dtId property is ignored.
        in: body
        required: true
        schema:
          type: object
      - $ref: '#/parameters/if-none-match-star'
      - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DigitalTwin'
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Put Digitaltwins Id
    delete:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsDelete
      description: Deletes a digital twin. All relationships referencing the digital twin must already be deleted.<br>Status codes:<br>* 204 No Content<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id is invalid.<br>  * RelationshipsNotDeleted - The digital twin contains relationships.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>* 412 Precondition Failed<br>  * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
      x-ms-examples:
        Delete a digital twin:
          $ref: ./examples/DeleteTwin.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/if-match'
      - $ref: '#/parameters/api-version'
      responses:
        '204':
          description: Success
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Delete Digitaltwins Id
    patch:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsUpdate
      description: Updates a digital twin.<br>Status codes:<br>* 204 No Content<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id or payload is invalid.<br>  * JsonPatchInvalid - The JSON Patch provided is invalid.<br>  * ValidationFailed - Applying the patch results in an invalid digital twin.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>* 412 Precondition Failed<br>  * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
      consumes:
      - application/json-patch+json
      x-ms-examples:
        Update a digital twin:
          $ref: ./examples/PatchTwinBasicExample.json
        Update a digital twin (multiple updates):
          $ref: ./examples/PatchTwinAdvancedExample.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - name: patchDocument
        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, replace and remove.
        in: body
        required: true
        schema:
          type: array
          items:
            type: object
      - $ref: '#/parameters/if-match'
      - $ref: '#/parameters/api-version'
      responses:
        '204':
          description: Success
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Patch Digitaltwins Id
  /digitaltwins/{id}/relationships/{relationshipId}:
    parameters:
    - $ref: '#/parameters/traceparent'
    - $ref: '#/parameters/tracestate'
    get:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsGetrelationshipbyid
      description: Retrieves a relationship between two digital twins.<br>Status codes:<br>* 200 OK<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id or relationship id is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>  * RelationshipNotFound - The relationship was not found.
      x-ms-examples:
        Get a relationship by id:
          $ref: ./examples/GetRelationshipById.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/relationshipId'
      - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Relationship'
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Digitaltwins Id Relationships Relationshipid
    put:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsAddrelationship
      description: Adds a relationship between two digital twins.<br>Status codes:<br>* 200 OK<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id, relationship id, or payload is invalid.<br>  * InvalidRelationship - The relationship is invalid.<br>  * OperationNotAllowed - The relationship cannot connect to the same digital twin.<br>  * ValidationFailed - The relationship content is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>  * TargetTwinNotFound - The digital twin target of the relationship was not found.<br>* 412 Precondition Failed<br>  * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
      x-ms-examples:
        Create a relationship:
          $ref: ./examples/CreateRelationshipBasicExample.json
        Create a relationship (with properties):
          $ref: ./examples/CreateRelationshipAdvancedExample.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/relationshipId'
      - name: relationship
        in: body
        description: The data for the relationship.
        required: true
        schema:
          type: object
      - $ref: '#/parameters/if-none-match-star'
      - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Relationship'
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Put Digitaltwins Id Relationships Relationshipid
    delete:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsDeleterelationship
      description: Deletes a relationship between two digital twins.<br>Status codes:<br>* 204 No Content<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id or relationship id is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>  * RelationshipNotFound - The relationship was not found.<br>* 412 Precondition Failed<br>  * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
      x-ms-examples:
        Delete a relationship:
          $ref: ./examples/DeleteRelationship.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/relationshipId'
      - $ref: '#/parameters/if-match'
      - $ref: '#/parameters/api-version'
      responses:
        '204':
          description: Success
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Delete Digitaltwins Id Relationships Relationshipid
    patch:
      tags:
      - Twins
      consumes:
      - application/json-patch+json
      operationId: microsoftAzureDigitaltwinsUpdaterelationship
      description: Updates the properties on a relationship between two digital twins.<br>Status codes:<br>* 204 No Content<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id or relationship id is invalid.<br>  * InvalidRelationship - The relationship is invalid.<br>  * JsonPatchInvalid - The JSON Patch provided is invalid.<br>  * ValidationFailed - The relationship content is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>  * RelationshipNotFound - The relationship was not found.<br>* 409 Conflict<br>  * RelationshipAlreadyExists - The relationship already exists.<br>* 412 Precondition Failed<br>  * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
      x-ms-examples:
        Update relationship properties:
          $ref: ./examples/PatchRelationshipBasicExample.json
        Update relationship properties (multiple updates):
          $ref: ./examples/PatchRelationshipAdvancedExample.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/relationshipId'
      - name: patchDocument
        description: JSON Patch description of the update to the relationship properties.
        in: body
        required: true
        schema:
          type: array
          items:
            type: object
      - $ref: '#/parameters/if-match'
      - $ref: '#/parameters/api-version'
      responses:
        '204':
          description: Success
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Patch Digitaltwins Id Relationships Relationshipid
  /digitaltwins/{id}/relationships:
    parameters:
    - $ref: '#/parameters/traceparent'
    - $ref: '#/parameters/tracestate'
    get:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsListrelationships
      description: Retrieves the relationships from a digital twin.<br>Status codes:<br>* 200 OK<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.
      x-ms-pageable:
        nextLinkName: nextLink
      x-ms-examples:
        List relationships:
          $ref: ./examples/GetRelationship.json
        List relationships by name:
          $ref: ./examples/GetRelationshipByRelationshipName.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - name: relationshipName
        description: The name of the relationship.
        in: query
        required: false
        type: string
      - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/RelationshipCollection'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Digitaltwins Id Relationships
  /digitaltwins/{id}/incomingrelationships:
    parameters:
    - $ref: '#/parameters/traceparent'
    - $ref: '#/parameters/tracestate'
    get:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsListincomingrelationships
      description: Retrieves all incoming relationship for a digital twin.<br>Status codes:<br>* 200 OK<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.
      x-ms-pageable:
        nextLinkName: nextLink
      x-ms-examples:
        List incoming relationships:
          $ref: ./examples/GetIncomingRelationship.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/IncomingRelationshipCollection'
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Digitaltwins Id Incomingrelationships
  /digitaltwins/{id}/telemetry:
    parameters:
    - $ref: '#/parameters/traceparent'
    - $ref: '#/parameters/tracestate'
    post:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsSendtelemetry
      description: Sends telemetry on behalf of a digital twin.<br>Status codes:<br>* 204 No Content<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id or message id is invalid.<br>  * ValidationFailed - The telemetry content is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.
      x-ms-examples:
        Send telemetry:
          $ref: ./examples/SendTelemetry.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - name: telemetry
        in: body
        description: The telemetry measurements to send from the digital twin.
        required: true
        schema:
          type: object
      - name: Message-Id
        in: header
        description: A unique message identifier (in the scope of the digital twin id) that is commonly used for de-duplicating messages.
        required: true
        type: string
      - name: Telemetry-Source-Time
        in: header
        description: An RFC 3339 timestamp that identifies the time the telemetry was measured.
        required: false
        type: string
      - $ref: '#/parameters/api-version'
      responses:
        '204':
          description: Success
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Post Digitaltwins Id Telemetry
  /digitaltwins/{id}/components/{componentPath}/telemetry:
    parameters:
    - $ref: '#/parameters/traceparent'
    - $ref: '#/parameters/tracestate'
    post:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsSendcomponenttelemetry
      description: Sends telemetry on behalf of a component in a digital twin.<br>Status codes:<br>* 204 No Content<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id, message id, or component path is invalid.<br>  * ValidationFailed - The telemetry content is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>  * ComponentNotFound - The component path was not found.
      x-ms-examples:
        Send telemetry in a component:
          $ref: ./examples/SendTelemetryFromComponent.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/componentPath'
      - name: telemetry
        in: body
        description: The telemetry measurements to send from the digital twin's component.
        required: true
        schema:
          type: object
      - name: Message-Id
        in: header
        description: A unique message identifier (in the scope of the digital twin id) that is commonly used for de-duplicating messages.
        required: true
        type: string
      - name: Telemetry-Source-Time
        in: header
        description: An RFC 3339 timestamp that identifies the time the telemetry was measured.
        required: false
        type: string
      - $ref: '#/parameters/api-version'
      responses:
        '204':
          description: Success
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Post Digitaltwins Id Components Componentpath Telemetry
  /digitaltwins/{id}/components/{componentPath}:
    parameters:
    - $ref: '#/parameters/traceparent'
    - $ref: '#/parameters/tracestate'
    get:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsGetcomponent
      description: Retrieves a component from a digital twin.<br>Status codes:<br>* 200 OK<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id or component path is invalid.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>  * ComponentNotFound - The component path was not found.
      x-ms-examples:
        Get a component in a digital twin:
          $ref: ./examples/GetComponent.json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/componentPath'
      - $ref: '#/parameters/api-version'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/Component'
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Get Digitaltwins Id Components Componentpath
    patch:
      tags:
      - Twins
      operationId: microsoftAzureDigitaltwinsUpdatecomponent
      description: Updates a component on a digital twin.<br>Status codes:<br>* 204 No Content<br>* 400 Bad Request<br>  * InvalidArgument - The digital twin id, component path, or payload is invalid.<br>  * JsonPatchInvalid - The JSON Patch provided is invalid.<br>  * ValidationFailed - Applying the patch results in an invalid digital twin.<br>* 404 Not Found<br>  * DigitalTwinNotFound - The digital twin was not found.<br>* 412 Precondition Failed<br>  * PreconditionFailed - The precondition check (If-Match or If-None-Match) failed.
      x-ms-examples:
        Update a component in a digital twin:
          $ref: ./examples/PatchComponentBasicExample.json
        Update a component in a digital twin (multiple updates):
          $ref: ./examples/PatchComponentAdvancedExample.json
      consumes:
      - application/json-patch+json
      parameters:
      - $ref: '#/parameters/digitalTwinId'
      - $ref: '#/parameters/componentPath'
      - name: patchDocument
        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, replace and remove.
        in: body
        required: true
        schema:
          type: array
          items:
            type: object
      - $ref: '#/parameters/if-match'
      - $ref: '#/parameters/api-version'
      responses:
        '204':
          description: Success
          headers:
            ETag:
              description: Weak Etag.
              type: string
        default:
          description: Default response.
          schema:
            $ref: '#/definitions/ErrorResponse'
      summary: Microsoft Azure Patch Digitaltwins Id Components Componentpath
definitions:
  ErrorResponse:
    description: Error response.
    required:
    - error
    properties:
      error:
        $ref: '#/definitions/Error'
        description: The error details.
  IncomingRelationship:
    type: object
    description: An incoming relationship.
    properties:
      $relationshipId:
        type: string
        description: A user-provided string representing the id of this relationship, unique in the context of the source digital twin, i.e. sourceId + relationshipId is unique in the context of the service.
      $sourceId:
        type: string
        description: The id of the source digital twin.
      $relationshipName:
        type: string
        description: The name of the relationship.
      $relationshipLink:
        type: string
        description: Link to the relationship, to be used for deletion.
  IncomingRelationshipCollection:
    description: A collection of incoming relationships which relate digital twins together.
    type: object
    required:
    - value
    properties:
      value:
        type: array
        items:
          $ref: '#/definitions/IncomingRelationship'
      nextLink:
        type: string
        description: A URI to retrieve the next page of objects.
  RelationshipCollection:
    description: A collection of relationships which relate digital twins together.
    type: object
    required:
    - value
    properties:
      value:
        description: The relationship objects.
        type: array
        items:
          description: The relationship JSON document.
          type: object
      nextLink:
        description: A URI to retrieve the next page of objects.
        type: string
  Component:
    description: Digital twin component
    type: object
    additionalProperties: {}
  Relationship:
    description: Digital twin relationship
    type: object
    additionalProperties: {}
  DigitalTwin:
    description: Digital twin
    type: object
    additionalProperties: {}
  InnerError:
    description: A more specific error description than was provided by the containing error.
    properties:
      code:
        description: A more specific error code than was provided by the containing error.
        type: string
      innererror:
        description: An object containing more specific information than the current object about the error.
        $ref: '#/definitions/InnerError'
  Error:
    description: Error definition.
    properties:
      code:
        description: Service specific error code which serves as the substatus for the HTTP error code.
        type: string
        readOnly: true
      message:
        description: A human-readable representation of the error.
        type: string
        readOnly: true
      details:
        description: Internal error details.
        type: array
        items:
          $ref: '#/definitions/Error'
        readOnly: true
      innererror:
        description: An object containing more specific information than the current object about the error.
        $ref: '#/definitions/InnerError'
parameters:
  tracestate:
    name: tracestate
    in: header
    description: Provides vendor-specific trace identification information and is a companion to traceparent.
    required: false
    type: string
    x-ms-parameter-location: method
    x-ms-parameter-grouping:
      postfix: Options
  traceparent:
    name: traceparent
    in: header
    description: Identifies the request in a distributed tracing system.
    required: false
    type: string
    x-ms-parameter-location: method
    x-ms-parameter-grouping:
      postfix: Options
  componentPath:
    name: componentPath
    in: path
    description: The name of the DTDL component.
    type: string
    required: true
    x-ms-parameter-location: method
  digitalTwinId:
    name: id
    in: path
    description: The id of the digital twin. The id is unique within the service and case sensitive.
    type: string
    required: true
    x-ms-parameter-location: method
  if-none-match-star:
    name: If-None-Match
    in: header
    description: Only perform the operation if the entity does not already exist.
    required: false
    type: string
    enum:
    - '*'
    x-ms-parameter-location: method
    x-ms-parameter-grouping:
      postfix: Options
  if-match:
    name: If-Match
    in: header
    description: Only perform the operation if the entity's etag matches one of the etags provided or * is provided.
    required: false
    type: string
    x-ms-parameter-location: method
    x-ms-parameter-grouping:
      postfix: Options
  relationshipId:
    name: relationshipId
    description: The id of the relationship. The id is unique within the digital twin and case sensitive.
    in: path
    required: true
    type: string
    x-ms-parameter-location: method
  api-version:
    name: api-version
    in: query
    description: The requested API version.
    required: true
    type: string
    minLength: 1
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'