Digital Twins
A digital twin can perform actions on your behalf. It can access information, and be assigned assets that it can utilize in its actions.
A digital twin is contained, and accessed within the context of a specific organization.
You can create as many twins as you require to represent things, people, or items. Or you can have one twin that can perform many actions.
Listing All Active Twins
Lists all public twins, twins that provide a service, and all twins that are a part of your organization
curl --location --request GET '<API_URL>/twins/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Authorization: Token <ACCESS_TOKEN>'
{
"links": {
"first": "<URL>",
"last": "<URL>",
"next": null,
"prev": null
},
"data": [
{
"type": "twins",
"id": "<TWIN_ID>",
"attributes": {
"created": "2022-08-01T13:54:14.774295Z",
"modified": "2022-08-01T13:54:14.774295Z",
"name": "",
"description": "",
"personal": true,
"connections": [],
"personality": {
"id": "<PERSONALITY_ID>",
"characteristics": [],
"services": []
},
"meta-data": {},
"place-id": "",
"provider": "",
"location": null,
"opening-hours": {},
"phone-number": "",
"address": "",
"city": "",
"state": "",
"website": "",
"provider-info": {}
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "<ORG_ID>"
}
}
}
},
}
],
"meta": {
"pagination": {
"page": 1,
"pages": 1,
"count": 2
}
}
}
Listing all twins via GeoJson content type
To render a list of twins on a map, you can use the geo-json content type to only return the location information/
An example request would look like the following:
curl --location --request GET '<API_URL>/twins/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Authorization: Token <ACCESS_TOKEN>'
--header 'Content-Type: application/geo+json' \
This would return a response similar to the below:
{
"links": {
"first": "https://api.fetch.ai/twins/?page_number=1",
"last": "https://api.fetch.ai/twins/?page_number=6",
"next": "https://api.fetch.ai/twins/?page_number=2",
"prev": null
},
"data": {
"results": {
"type": "FeatureCollection",
"features": [
{
"id": "0bba61e1-fbbe-4f1c-b09f-da3587cda548",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-97.7245464,
30.2621351
]
},
"properties": {
"twin_id": "<TWIN_ID>",
"name": "<TWIN_NAME>",
"description": ""
}
},
]
},
"meta": {
"pagination": {
"page": 1,
"pages": 6,
"count": 114
}
},
"links": {
"first": "https://api.fetch.ai/twins/?page_number=1",
"last": "https://api.fetch.ai/twins/?page_number=6",
"next": "https://api.fetch.ai/twins/?page_number=2",
"prev": null
}
},
"meta": {
"pagination": {
"page": 1,
"pages": 6,
"count": 114
}
}
}
Query Parameters
| Query Parameters | Expected Input | Description |
|---|---|---|
| is_public | BOOLEAN | returns twins that are publically accessible |
| is_personal | BOOLEAN | returns twins that you own or control |
| personality | TwinID | returns twins matching personality of provided twinID |
| characteristics | String, comma separated list | returns twins that match characteristics provided |
| organization | OrgID | shows only twins in given organization |
| is_connection | BOOLEAN | returns twins that are connected to your twin |
| is_supplier | BOOLEAN | returns twins that publically provide a product or service |
Listing All Active Twins in My Organization
Lists all twins that are included in your organization
curl --location --request GET '<API_URL>/my/twins/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Authorization: Token <ACCESS_TOKEN>'
{
"data": [
{
"type": "twins",
"id": "<TWIN_ID>",
"attributes": {
"created": "2022-08-01T13:54:14.774295Z",
"modified": "2022-08-01T13:54:14.774295Z",
"name": "",
"description": "",
"personal": true,
"connections": [],
"personality": {
"id": "<PERSONALITY_ID>",
"characteristics": [],
"services": []
},
"meta-data": {}
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "<ORG_ID>"
}
}
}
},
...
]
}
Displaying Details for a Specific Twin
To get details about a specific twin, you can query the /twins/ url and append the specific twin ID as shown below:
curl --location --request GET '<API_URL>/twins/<TWIN_ID>/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Authorization: Token <ACCESS_TOKEN>'
--header 'Content-Type: application/vnd.api+json' \
This will return a response like the following:
{
"data": {
"type": "twins",
"id": "<TWIN_ID>",
"attributes": {
"created": "2022-05-05T19:29:28.375707Z",
"modified": "2022-08-12T17:28:11.896910Z",
"name": "<TWIN_NAME>",
"description": "<TWIN_DESCRIPTION>",
"tasks_supplied": 4,
"personal": false,
"meta_data": {
"city": "",
"name": "",
"phone": "",
"state": "",
"street": "",
"address": "",
"country": "",
"service": [
"dine in",
"beer bar",
"wifi",
"african"
],
"twitter": "",
"website": "",
"zipCode": "",
"category": "",
"facebook": "",
"latitude": <LATITUDE>,
"location": {
"type": "Point",
"coordinates": [
<LONGITUDE>,
<LATITUDE>
]
},
"place_id": "",
"provider": "Google Places API",
"instagram": "",
"longitude": <LONGITUDE>,
"timeTable": {
"2": {
"day": "Tuesday",
"endTime": 21,
"startTime": 11
},
"3": {
"day": "Wednesday",
"endTime": 21,
"startTime": 11
},
"4": {
"day": "Thursday",
"endTime": 22,
"startTime": 11
},
"5": {
"day": "Friday",
"endTime": 23,
"startTime": 11
},
"6": {
"day": "Saturday",
"endTime": 23,
"startTime": 11
},
"7": {
"day": "Sunday",
"endTime": 20,
"startTime": 11
}
},
"priceRange": "budget",
"subCategory": "bar / pub",
"phone_number": "",
"opening_hours": [
"Monday: Closed",
"Tuesday: 11:00 AM – 10:00 PM",
"Wednesday: 11:00 AM – 10:00 PM",
"Thursday: 11:00 AM – 10:00 PM",
"Friday: 11:00 AM – 11:00 PM",
"Saturday: 11:00 AM – 11:00 PM",
"Sunday: 11:00 AM – 8:00 PM"
],
"provider_info": {
"photos": [
{
"width": ,
"height": ,
"photo_reference": "",
"html_attributions": [
""
]
},
],
"reviews": [
{
"text": "",
"time": <TIMESTAMP>,
"rating": 5,
"language": "en",
"author_url": "",
"author_name": "",
"profile_photo_url": "",
"relative_time_description": ""
},
]
}
},
"place_id": "",
"provider": "Google Places API",
"location": {
"type": "Point",
"coordinates": [
<LONGITUDE>,
<LATITUDE>
]
},
"opening_hours": [
"Monday: Closed",
"Tuesday: 11:00 AM – 10:00 PM",
"Wednesday: 11:00 AM – 10:00 PM",
"Thursday: 11:00 AM – 10:00 PM",
"Friday: 11:00 AM – 11:00 PM",
"Saturday: 11:00 AM – 11:00 PM",
"Sunday: 11:00 AM – 8:00 PM"
],
"phone_number": "",
"address": "",
"city": "",
"state": "",
"website": "",
"provider_info": {
"photos": [
{
"width": ,
"height": ,
"photo_reference": "",
"html_attributions": [
""
]
},
{
"width": ,
"height": ,
"photo_reference": "",
"html_attributions": [
""
]
},
],
"reviews": [
{
"text": "",
"time": <TIMESTAMP>,
"rating": 5,
"language": "en",
"author_url": "",
"author_name": "",
"profile_photo_url": "",
"relative_time_description": ""
},
]
},
"tags": [
"establishment",
"food",
"point-of-interest"
]
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "<ORG_ID>"
}
}
}
}
}
Creating a New Twin
To add a new twin, you can send a POST request to the the my/twins/ URL as shown below:
curl --location --request POST '<API_URL>/my/twins/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Token <ACCESS_TOKEN>'
--data-raw '
{
"data": {
"type": "twins",
"attributes": {
"name": "<YOUR TWIN NAME>",
"description": "<THIS FIELD IS OPTIONAL>"
},
},
}'
Modifying Details For a Specific Twin
To modify details about your twin, you can send a PATH request to the /my/twins/ url, and appending the specific twin ID to the end of the URL as shown below:
curl --location --request PATCH '<API_URL>/my/twins/<TWIN_ID>/' \
--header 'X-Organization: <ORG_ID>' \
--header 'Authorization: Token <ACCESS_TOKEN>'
--header 'Content-Type: application/vnd.api+json' \
--data-raw '
{
"data": {
"type":
"twins",
"attributes": {
"name": "<UPDATED NAME>",
"description": "<UPDATED DESCRIPTION>"
}
}
}'