openapi: 3.1.0
info:
title: TagoIO Access Management Dashboards API
description: "#### **How to use this documentation**\nThe documentation is split by which token you're required to use in the request. \nTagoIO provides 4 different tokens:\n- **Device-Token**: The token from your device, which you can get from the device's page.\n \n- **Profile-Token**: Also know as Account-Token. You get from your profile settings page.\n \n- **Network-Token**: Is the token from your Network. Only available if you're owner of the network in your integrations page.\n \n- **Analysis-Token:** The token from your analysis, available in the analysis page.\n---\n#### Setting the API Endpoint Region\nWhen making a request to the TagoIO API, you must also specify the appropriate regional endpoint. Choose one of the following endpoints based on your geographical region:\n\n- **United States East 1:** \n Use this endpoint when your application is based in the eastern United States. \n **URL:** `https://api.us-e1.tago.io/`\n \n- **Europe West 1:** \n Use this endpoint when your application is based in Western Europe. \n **URL:** `https://api.eu-w1.tago.io/`\n\n- **Tago Deploy:** \n You should use your own API URL that is available in your Domains section of the TagoDeploy."
version: 1.0.0
contact: {}
servers:
- url: https://api.us-e1.tago.io
- url: https://api.eu-w1.tago.io
security:
- ProfileToken: []
tags:
- name: Dashboards
description: Manage dashboards (Profile Token).
paths:
/dashboard/{dashboardID}:
parameters:
- name: dashboardID
in: path
required: true
schema:
type: string
example: (Type a dashboard ID)
get:
tags:
- Dashboards
summary: Dashboard Information
description: 'Get settings information of the dashboard.
'
operationId: getInformation
responses:
'200':
description: Getting a dashboard information
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
arrangement:
type: array
items:
type: object
properties:
height:
type: number
example: 3
tab:
example: null
widget_id:
type: string
example: 6230e740f5772600124c81e1
width:
type: number
example: 1
x:
type: number
example: 0
y:
type: number
example: 0
example:
- height: 3
tab: null
widget_id: 6230e740f5772600124c81e1
width: 1
x: 0
y: 0
- height: 3
tab: null
widget_id: 6230e75df5772600124c81e2
width: 1
x: 1
y: 0
- height: 3
tab: null
widget_id: 6230e44cf5772600124c81de
width: 1
x: 2
y: 0
- height: 3
tab: null
widget_id: 6230e84df5772600124c81e7
width: 2.3333333333333335
x: 0.3333333333333333
y: 7
- height: 5
tab: null
widget_id: 62750cf1253eb800126aefc0
width: 2
x: 2.666666666666667
y: 7
background:
type: object
properties: {}
blueprint_device_behavior:
example: null
blueprint_devices:
type: array
items:
type: object
properties:
conditions:
type: array
items:
type: object
properties:
key:
type: string
example: kmutable
value:
type: string
example: vmutable
example:
- key: kmutable
value: vmutable
filter_conditions:
type: array
items: {}
example: []
id:
type: string
example: 6230e392f5772600124c81db
name:
type: string
example: mutable_device
example:
- conditions:
- key: kmutable
value: vmutable
filter_conditions: []
id: 6230e392f5772600124c81db
name: mutable_device
- conditions:
- key: kimmutable
value: vimmutable
filter_conditions: []
id: 6230e42af5772600124c81dc
name: immutable_device
- conditions:
- key: klegacy
value: vlegacy
filter_conditions: []
id: 6230e42af5772600124c81dd
name: legacy_device
blueprint_selector_behavior:
example: null
created_at:
type: string
example: '2022-03-15T19:05:54.839Z'
group_by:
type: array
items: {}
example: []
icon:
type: object
properties: {}
id:
type: string
example: 6230e392f5772600124c81da
label:
type: string
example: Device Types Blueprint
last_access:
type: string
example: '2022-06-21T11:51:07.642Z'
setup:
type: object
properties: {}
tabs:
type: array
items: {}
example: []
tags:
type: array
items: {}
example: []
theme:
example: null
type:
type: string
example: blueprint
updated_at:
type: string
example: '2022-06-21T11:51:07.642Z'
visible:
type: boolean
example: true
status:
type: boolean
example: true
examples:
Getting a dashboard information:
value:
result:
arrangement:
- height: 3
tab: null
widget_id: 6230e740f5772600124c81e1
width: 1
x: 0
y: 0
- height: 3
tab: null
widget_id: 6230e75df5772600124c81e2
width: 1
x: 1
y: 0
- height: 3
tab: null
widget_id: 6230e44cf5772600124c81de
width: 1
x: 2
y: 0
- height: 3
tab: null
widget_id: 6230e84df5772600124c81e7
width: 2.3333333333333335
x: 0.3333333333333333
y: 7
- height: 5
tab: null
widget_id: 62750cf1253eb800126aefc0
width: 2
x: 2.666666666666667
y: 7
background: {}
blueprint_device_behavior: null
blueprint_devices:
- conditions:
- key: kmutable
value: vmutable
filter_conditions: []
id: 6230e392f5772600124c81db
name: mutable_device
- conditions:
- key: kimmutable
value: vimmutable
filter_conditions: []
id: 6230e42af5772600124c81dc
name: immutable_device
- conditions:
- key: klegacy
value: vlegacy
filter_conditions: []
id: 6230e42af5772600124c81dd
name: legacy_device
blueprint_selector_behavior: null
created_at: '2022-03-15T19:05:54.839Z'
group_by: []
icon: {}
id: 6230e392f5772600124c81da
label: Device Types Blueprint
last_access: '2022-06-21T11:51:07.642Z'
setup: {}
tabs: []
tags: []
theme: null
type: blueprint
updated_at: '2022-06-21T11:51:07.642Z'
visible: true
status: true
put:
tags:
- Dashboards
summary: Edit Dashboard
description: "Modify any property of the dashboard\n\n:::warning\nThe arrangement is **not automatically populated** when you create a widget. \nAfter creating a widget, you **must manually edit the arrangement field** to include the new widget and specify its position in the dashboard.\n:::\n\nEach item in the arrangement array represents a widget's placement and sizing.\n"
operationId: editDashboard
requestBody:
content:
application/json:
schema:
type: object
properties:
label:
type: string
description: The Dashboard Label
type:
type: string
enum:
- dashboard
- blueprint
example: blueprint
description: The type of dashboard. Can be "dashboard" or "blueprint".
group_by:
type: array
items: {}
visible:
type: boolean
example: true
description: Determines if the dashboard is visible in the sidebar. If set to false, the dashboard remains accessible from the Dashboard list.
icon:
type: object
properties:
color:
type: string
example: hsl(328, 89%, 47%)
url:
type: string
example: https://svg.internal.tago.io/arrowheads-pointing-to-the-left.svg
tabs:
type: array
items:
type: object
properties:
key:
type: string
example: '1648142133869'
link:
type: string
example: ''
value:
type: string
example: new tab test
example:
- key: '1648142133869'
link: ''
value: new tab test
- key: '1648142564354'
link: ''
value: 'new tab 2 '
- key: '1648142571171'
link: ''
value: 'new tab 3 '
tags:
type: array
items:
type: object
properties:
key:
type: string
example: updatedkey
value:
type: string
example: updatedvalue
example:
- key: updatedkey
value: updatedvalue
- key: updatedkey
value: updatedvalue
blueprint_devices:
type: array
description: 'Only present for dashboards of type "blueprint".
Defines the list of devices associated with a blueprint dashboard. Each device entry describes a device type, its conditions, and optional filter conditions.
'
items:
type: object
properties:
id:
type: string
description: The unique identifier of the blueprint device.
example: 68d2f3e0a6343f0009318e4c
name:
type: string
description: The name of the blueprint.
example: sensor
type:
type: string
description: The type of the blueprint.
enum:
- device
- entity
example: device
conditions:
type: array
description: List of tag conditions that define this blueprint's characteristics.
items:
type: object
properties:
key:
type: string
description: The condition key.
example: is_sensor
value:
type: string
description: The condition value.
example: 'true'
example:
- key: is_sensor
value: 'true'
filter_conditions:
type: array
description: Optional filter conditions for the device.
items:
type: object
properties:
type:
type: string
description: The type of filter condition.
example: tag_match
tag_key:
type: string
description: The tag key to match.
example: location
blueprint_device:
type: string
description: The name of the blueprint device to match against.
example: customer
example:
- type: tag_match
tag_key: location
blueprint_device: customer
example:
- id: 68d2f3e0a6343f0009318e4c
name: sensor
type: device
conditions:
- key: is_sensor
value: 'true'
filter_conditions: []
- id: 68d2f3e0a6343f0009318e4d
name: customer
type: device
conditions:
- key: company
value: JohnDoe
filter_conditions: []
arrangement:
type: array
description: 'The arrangement property defines the layout and positioning of widgets within the dashboard grid.
'
items:
type: object
properties:
height:
type: number
example: 3
description: The height of the widget in grid units.
tab:
description: The tab identifier if the widget is placed in a tab, or null.
example: null
widget_id:
type: string
example: 6230e740f5772600124c81e1
description: The ID of the widget.
width:
type: number
example: 1
description: The width of the widget in grid units.
x:
type: number
example: 0
description: The X (column) position of the widget in the grid.
y:
type: number
example: 0
description: The Y (row) position of the widget in the grid.
example:
- height: 3
tab: null
widget_id: 6230e740f5772600124c81e1
width: 1
x: 0
y: 0
- height: 3
tab: null
widget_id: 6230e75df5772600124c81e2
width: 1
x: 1
y: 0
- height: 3
tab: null
widget_id: 6230e44cf5772600124c81de
width: 1
x: 2
y: 0
- height: 3
tab: null
widget_id: 6230e84df5772600124c81e7
width: 2.33
x: 0.33
y: 7
- height: 5
tab: null
widget_id: 62750cf1253eb800126aefc0
width: 2
x: 2.67
y: 7
responses:
'200':
description: Updating a dashboard information
content:
application/json:
schema:
type: object
properties:
result:
type: string
example: Successfully Updated
status:
type: boolean
example: true
examples:
Updating a dashboard information:
value:
result: Successfully Updated
status: true
delete:
tags:
- Dashboards
summary: Delete Dashboard
description: 'Delete the dashboard
'
operationId: deleteDashboard
responses:
'200':
description: Deleting a dashboard
content:
application/json:
schema:
type: object
properties:
result:
type: string
example: Successfully Removed
status:
type: boolean
example: true
examples:
Deleting a dashboard:
value:
result: Successfully Removed
status: true
/dashboard:
get:
tags:
- Dashboards
summary: List Dashboards
description: 'Retrieves a list with all dashboards from the profile
'
operationId: listDashboards
parameters:
- name: page
in: query
schema:
type: string
example: '1'
description: Page number.
- name: amount
in: query
schema:
type: string
example: '5'
description: Amount of dashboards per page.
- name: orderBy
in: query
schema:
type: string
example: name
description: Order dashboard by name.
- name: fields[]
in: query
description: 'Select which properties to include for each dashboard in the response.
Pass the parameter multiple times to include more than one field.
Example: `?fields[]=label&fields[]=id&fields[]=type`
'
schema:
type: array
items:
type: string
enum:
- label
- id
- type
- tags
- visible
- created_at
- last_access
style: form
explode: true
responses:
'200':
description: Get a list of dashboards
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: Dashboard ID
example: 623c74a15a13360011803f3e
label:
type: string
description: Dashboard title label
example: Door Sensor
tags:
type: array
description: Dashboard tags
items:
type: object
properties:
key:
type: string
example: vehicle
value:
type: string
example: gas
example: []
profile:
type: string
description: Profile ID
example: 612ea05e3cc0780012715111
visible:
type: boolean
description: Visibility status
example: true
group_by:
type: array
description: List of tags to group in the sidebar
items:
type: string
example: []
created_at:
type: string
format: date-time
description: Creation timestamp
example: '2022-03-24T13:39:45.504Z'
icon:
type: object
description: Dashboard icon
properties:
color:
type: string
example: hsl(328, 89%, 47%)
url:
type: string
example: https://svg.internal.tago.io/arrowheads-pointing-to-the-left.svg
example: {}
last_access:
type: string
format: date-time
description: Last access timestamp
example: '2022-06-13T20:53:32.583Z'
type:
type: string
description: Dashboard type
enum:
- dashboard
- blueprint
example: dashboard
tabs:
type: array
description: Dashboard tabs
items:
type: object
properties:
key:
type: string
example: '1648142133869'
link:
type: string
example: ''
value:
type: string
example: tab test
example: []
post:
tags:
- Dashboards
summary: Create Dashboard
description: 'Creates a dashboard of type Blueprint or Normal Dashboard into your profile.
It''s recommended to access your Admin Developer panel and Copy the Dashboard JSON Structure to see all available fields.
'
operationId: createDashboard
requestBody:
content:
application/json:
schema:
type: object
required:
- label
- type
properties:
group_by:
type: array
items: {}
description: List of tags to group in the sidebar
example: []
icon:
type: object
properties:
color:
type: string
example: hsl(328, 89%, 47%)
url:
type: string
example: https://svg.internal.tago.io/arrowheads-pointing-to-the-left.svg
label:
type: string
example: Tracker dashboard
tabs:
type: array
items:
type: object
properties:
key:
type: string
example: '1648142133869'
link:
type: string
example: ''
value:
type: string
example: tab test
example:
- key: '1648142133869'
link: ''
value: tab test
- key: '1648142564354'
link: ''
value: 'tab 2 '
- key: '1648142571171'
link: ''
value: 'tab 3 '
tags:
type: array
items:
type: object
properties:
key:
type: string
example: vehicle
value:
type: string
example: gas
example:
- key: vehicle
value: gas
- key: speed
value: mph
type:
type: string
enum:
- dashboard
- blueprint
example: blueprint
description: The type of dashboard. Can be "dashboard" or "blueprint".
visible:
type: boolean
example: true
default: true
examples:
Create Dashboard:
value:
group_by: []
icon:
color: hsl(328, 89%, 47%)
url: https://svg.internal.tago.io/arrowheads-pointing-to-the-left.svg
label: Tracker dashboard
profile: 612ea05e3cc0780012715111
tabs:
- key: '1648142133869'
link: ''
value: tab test
- key: '1648142564354'
link: ''
value: 'tab 2 '
- key: '1648142571171'
link: ''
value: 'tab 3 '
tags:
- key: vehicle
value: gas
- key: speed
value: mph
type: dashboard
visible: true
responses:
'201':
description: Creating a dashboard
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
dashboard:
type: string
example: 614e0aa36f480300126652f9a38
status:
type: boolean
example: true
examples:
Creating a dashboard:
value:
result:
dashboard: 614e0aa36f480300126652f9a38
status: true
/dashboard/{dashboardID}/duplicate:
parameters:
- name: dashboardID
in: path
required: true
schema:
type: string
example: (Type a dashboard ID)
post:
tags:
- Dashboards
summary: Duplicate Dashboard
description: "Duplicate an existing dashboard, including its configuration, widgets, and settings. \nOptionally, set a new label for the duplicated dashboard and provide setup parameters to customize the copy. \n\nUse this endpoint to quickly clone dashboards for reuse or further customization.\n"
operationId: duplicateDashboard
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
new_label:
type: string
description: New label for the duplicated dashboard.
example: Ice Cream Machine and Freezer - Copy
setup:
type: object
description: Setup configuration for the duplicated dashboard.
properties:
is_configured:
type: boolean
description: Indicates if the dashboard is configured.
example: true
config:
type: array
description: List of configuration objects for the dashboard.
items:
type: object
properties:
id:
type: string
description: Analysis ID, Device ID, Blueprint Device/Entity ID.
example: 68c9baabb24379000ab1c8cc
name:
type: string
description: Reference name that will be displayed when setting up the copy.
example: Freezer Simulator
examples:
Duplicate dashboard:
value:
setup:
is_configured: true
config:
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tago-io/refs/heads/main/openapi/tago-io-dashboards-api-openapi.yml