# Scan Twins

This endpoint retrieves a list of Twin UUIDs of Twins owned by the account of the calling user after performing a Twin scan (if the details parameter is set to False) or details of the listed Twins (if the details parameter is set to True):

  • If the details parameter is set to False (default value), UUIDs of all Twins owned by the account of the calling user are returned, regardless whether they are visible to the calling user.
  • If the details parameter is set to True, only Twins visible to the calling user are returned. Please see the request details=True and response details=True sections for more information.
Method Path Operation*
GET /twins scan_twins

*

In order for a user to perform the "scan_twins" operation, the "scan_twins" permission must be included in the list of allowed actions in the statement of the user's role.

# Request

Parameter Type In Description
cursor
optional		 string query string Position of the cursor denoting where the scan of Twins should be started.
count
optional *		 integer query string, DEFAULT=100 Number of Twins to be scanned. The minimum number of Twins to be scanned is 1, the maximum is 1000.
match
optional **		 string query string Rule to be applied to the Twin scan.
details
optional ***		 boolean, DEFAULT=False query string Denotes whether the details of each Twin should be returned.

*

The "cursor" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, its default value is used, i.e. the scan is starting from the beginning of the list.

**

The "count" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, its default value is used.

**

The "match" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, no Rule is used when scanning the Twins.

***

The "details" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, a list of Twin UUIDs is returned.

# Response

Attribute Type Description
cursor string Position of the cursor denoting where the scan of Twins has finished. If no more Twins are to be scanned, the returned value is null.
uuid string Twin UUID.

# Request (details=True)

Parameter Type In Description
cursor
optional *		 string, DEFAULT= query string Position of the cursor denoting where the scan of Twins should be started.
count
optional **		 integer, DEFAULT=100 query string Number of Twins to be scanned. The minimum number of Twins to be scanned is 1, the maximum is 1000.
match
optional ***		 string query string Rule to be applied to the Twin scan.
details
optional ****		 boolean, DEFAULT=False query string Denotes whether the details of each Twin should be returned.

**

The "cursor" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, a new scan is started.

**

The "count" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, its default value is used.

**

The "match" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, no Rule is used when scanning Twins.

***

The "details" parameter is optional and does not need to be included in the query string of the request. If it is not included in the request, a list of Twin UUIDs is returned.

# Response (details=True)

Attribute Type Description
cursor string Position of the cursor denoting where the scan of Twins has finished. If no more Twins are to be scanned, the returned value is null.
owner string Account UUID of the account which is the current owner of the Twin. The ownership of a Twin can be transferred.
status string, value is "alive" or "terminated" The status of a Twin can be "alive" or "terminated". In case of alive Twins, the "description" can be updated by the owner of the Twin. In case of terminated Twins, the description field cannot be updated. Ledger Entries, Identities, and Docs can be attached to alive and terminated Twins by all users involved in the process.
updated_ts timestamp Time at which the Twin was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
description dictionary Attributes of the Twin defined by the owner in form of key-value pairs:
- key: It must match the regular expression(opens new window) ^[a-z_][0-9a-z_]{0,63}$.
- value: JSON compliant value.
Only the owner of the Twin can update the description of the Twin.
For more details consult the description field section.
creation_certificate dictionary
Certificate generated automatically by the system upon creation of a Twin. It cannot be modified after it has been generated.
Attribute Type Description
uuid string Twin UUID. It is generated automatically when a Twin is created and stored in the "uuid" field of the creation certificate.
creator string Account UUID of the account creating the Twin.
created_ts timestamp Time at which the Twin was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
termination_certificate dictionary
Certificate generated automatically by the system when a Twin is terminated. It cannot be modified after it has been generated.
Attribute Type Description
issuer string Account UUID of the account terminating the Twin.
terminated_ts timestamp Time at which the Twin was terminated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).

# Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.

← Update Twin →

Was this article helpful?