openapi: 3.1.0
info:
title: TagoIO Access Management Widgets 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: Widgets
description: Manage widgets (Profile Token).
paths:
/dashboard/{dashboardID}/widget/{widgetID}:
parameters:
- name: dashboardID
in: path
required: true
schema:
type: string
example: (Type a dashboard ID)
- name: widgetID
in: path
required: true
schema:
type: string
example: (Type a widget ID)
get:
tags:
- Widgets
summary: Widget Information
description: 'Retrieve the complete JSON structure of the dashboard widget, including all settings and data/resource instructions used to populate the widget''s data.
'
operationId: getWidgetInformation
responses:
'200':
description: Getting a widget information
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
analysis_run:
example: null
dashboard:
type: string
example: 623c74a15a13360011803f3e
data:
type: array
items:
type: object
properties:
origin:
type: string
example: 6238a3a27d792400139e5b47
query:
type: string
example: last_value
variables:
type: array
items:
type: string
example: temperature
example:
- temperature
example:
- origin: 6238a3a27d792400139e5b47
query: last_value
variables:
- temperature
- origin: 62308e38de51960019697e76
query: last_value
variables:
- temperature
display:
type: object
properties:
header_buttons:
type: array
items: {}
example: []
help:
type: string
example: ''
show_units:
type: boolean
example: true
show_variables:
type: boolean
example: true
theme:
type: object
properties:
color:
type: object
properties:
background:
type: string
example: hsla(332, 33%, 73%, 1)
button:
type: string
example: hsla(112, 91%, 58%, 1)
dot:
type: string
example: hsla(0, 97%, 48%, 1)
header:
type: string
example: hsla(336, 81%, 51%, 1)
variables:
type: array
items:
type: object
properties:
origin:
type: string
example: 6238a3a27d792400139e5b47
variable:
type: string
example: temperature
example:
- origin: 6238a3a27d792400139e5b47
variable: temperature
- origin: 62308e38de51960019697e76
variable: temperature
id:
type: string
example: 623c79da5a13360011819b1d
label:
type: string
example: 'Display #1'
realtime:
type: boolean
example: true
resource:
type: array
items: {}
example: []
token:
example: null
type:
type: string
example: display
status:
type: boolean
example: true
examples:
Getting a widget information:
value:
result:
analysis_run: null
dashboard: 623c74a15a13360011803f3e
data:
- origin: 6238a3a27d792400139e5b47
query: last_value
variables:
- temperature
- origin: 62308e38de51960019697e76
query: last_value
variables:
- temperature
display:
header_buttons: []
help: ''
show_units: true
show_variables: true
theme:
color:
background: hsla(332, 33%, 73%, 1)
button: hsla(112, 91%, 58%, 1)
dot: hsla(0, 97%, 48%, 1)
header: hsla(336, 81%, 51%, 1)
variables:
- origin: 6238a3a27d792400139e5b47
variable: temperature
- origin: 62308e38de51960019697e76
variable: temperature
id: 623c79da5a13360011819b1d
label: 'Display #1'
realtime: true
resource: []
token: null
type: display
status: true
put:
tags:
- Widgets
summary: Edit Widget
description: 'Edit properties of a JSON within a dashboard of your profile.
'
operationId: editWidget
requestBody:
content:
application/json:
schema:
type: object
properties:
dashboard:
type: string
example: 623c74a15a13360011803f3e
display:
type: object
properties:
header_buttons:
type: array
items: {}
show_units:
type: boolean
example: true
show_variables:
type: boolean
example: true
theme:
type: object
properties:
color:
type: object
properties:
background:
type: string
example: hsla(332, 33%, 73%, 1)
button:
type: string
example: hsla(112, 91%, 58%, 1)
dot:
type: string
example: hsla(0, 97%, 48%, 1)
header:
type: string
example: hsla(336, 81%, 51%, 1)
variables:
type: array
items:
type: object
properties:
origin:
type: string
example: 6238a3a27d792400139e5b47
variable:
type: string
example: temperature
example:
- origin: 6238a3a27d792400139e5b47
variable: temperature
- origin: 62308e38de51960019697e76
variable: temperature
label:
type: string
example: 'Display #1'
realtime:
type: boolean
example: true
type:
type: string
example: display
examples:
Card Widget Example:
value:
display:
alias: Ice Cream Widget
header_buttons:
- color: null
icon: ''
text: ''
trigger: widget
widget: null
frame_settings:
shadow:
hide: false
header_visibility: show_always
theme:
color:
background: hsl(210, 12%, 12%)
header: hsl(210, 65%, 60%)
text: hsl(210, 20%, 92%)
show_variables: true
formula:
enable: false
unit_type: origin
fixed_unit: ''
apply_all_matching_formulas: false
number_format:
decimals: -1
show_thousand: false
max_points: 10
show_chart: true
show_unit: true
url: ''
variable: temperature
data:
- qty: 10
origin: 68c9baabb24379000ab1c8cc
variables:
- temperature
resource: []
id: 68c9bab8fe8818000a7ec597
label: Temperature
realtime: null
type: card
cache: null
responses:
'200':
description: Editing a widget
content:
application/json:
schema:
type: object
properties:
result:
type: string
example: Successfully Updated
status:
type: boolean
example: true
examples:
Editing a widget:
value:
result: Successfully Updated
status: true
delete:
tags:
- Widgets
summary: Delete Widget
description: "Delete a widget from the dashboard.\n\n:::warning \n\nDeleting a widget does not automatically remove it from the dashboard arrangement. You must manually edit the dashboard arrangement to remove the deleted widget. \n\n:::\n"
operationId: deleteWidget
responses:
'200':
description: Deleting a Widget
content:
application/json:
schema:
type: object
properties:
result:
type: string
example: Successfully Removed
status:
type: boolean
example: true
examples:
Deleting a Widget:
value:
result: Successfully Removed
status: true
/data/{dashboardID}/{widgetID}:
parameters:
- name: dashboardID
in: path
required: true
schema:
type: string
example: (Type a dashboard ID)
- name: widgetID
in: path
required: true
schema:
type: string
example: (Type a widget ID)
get:
tags:
- Widgets
summary: Resolve Widget Data
description: 'Retrieve all the data necessary to display a widget, according to its configuration in the `data` and `resource` fields.
'
operationId: getWidgetData
responses:
'200':
description: Getting widget Data
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
content:
type: array
items:
type: object
properties:
data:
type: object
properties:
origin:
type: string
example: 6238a3a27d792400139e5b47
query:
type: string
example: last_value
variables:
type: array
items:
type: string
example: temperature
example:
- temperature
result:
type: array
items:
type: object
properties:
device:
type: string
example: 6238a3a27d792400139e5b47
group:
type: string
example: 3ac3e21100e473e57d9a1b26
id:
type: string
example: 62b1a9d75e374e00112e3ca4
origin:
type: string
example: 6238a3a27d792400139e5b47
serie:
type: string
example: 3ac3e21100e473e57d9a1b26
time:
type: string
example: '2022-06-21T11:21:59.415Z'
value:
type: number
example: 71
variable:
type: string
example: temperature
example:
- device: 6238a3a27d792400139e5b47
group: 3ac3e21100e473e57d9a1b26
id: 62b1a9d75e374e00112e3ca4
origin: 6238a3a27d792400139e5b47
serie: 3ac3e21100e473e57d9a1b26
time: '2022-06-21T11:21:59.415Z'
value: 71
variable: temperature
example:
- data:
origin: 6238a3a27d792400139e5b47
query: last_value
variables:
- temperature
result:
- device: 6238a3a27d792400139e5b47
group: 3ac3e21100e473e57d9a1b26
id: 62b1a9d75e374e00112e3ca4
origin: 6238a3a27d792400139e5b47
serie: 3ac3e21100e473e57d9a1b26
time: '2022-06-21T11:21:59.415Z'
value: 71
variable: temperature
- data:
origin: 62308e38de51960019697e76
query: last_value
variables:
- temperature
result:
- device: 62308e38de51960019697e76
id: 62309cb173cb3b001a031db5
metadata:
old_value: '45'
origin: 62308e38de51960019697e76
time: '2022-03-15T14:03:29.476Z'
unit: C
value: '33'
variable: temperature
widget:
type: object
properties:
analysis_run:
example: null
dashboard:
type: string
example: 623c74a15a13360011803f3e
data:
type: array
items:
type: object
properties:
origin:
type: string
example: 6238a3a27d792400139e5b47
query:
type: string
example: last_value
variables:
type: array
items:
type: string
example: temperature
example:
- temperature
example:
- origin: 6238a3a27d792400139e5b47
query: last_value
variables:
- temperature
- origin: 62308e38de51960019697e76
query: last_value
variables:
- temperature
display:
type: object
properties:
header_buttons:
type: array
items: {}
example: []
show_units:
type: boolean
example: true
show_variables:
type: boolean
example: true
theme:
type: object
properties:
color:
type: object
properties:
background:
type: string
example: hsla(332, 33%, 73%, 1)
button:
type: string
example: hsla(112, 91%, 58%, 1)
dot:
type: string
example: hsla(0, 97%, 48%, 1)
header:
type: string
example: hsla(336, 81%, 51%, 1)
variables:
type: array
items:
type: object
properties:
origin:
type: string
example: 6238a3a27d792400139e5b47
variable:
type: string
example: temperature
example:
- origin: 6238a3a27d792400139e5b47
variable: temperature
- origin: 62308e38de51960019697e76
variable: temperature
id:
type: string
example: 623c79da5a13360011819b1d
label:
type: string
example: 'Display #1'
realtime:
type: string
example: 'true'
resource:
type: array
items: {}
example: []
type:
type: string
example: display
status:
type: boolean
example: true
examples:
Getting widget Data:
value:
result:
content:
- data:
origin: 6238a3a27d792400139e5b47
query: last_value
variables:
- temperature
result:
- device: 6238a3a27d792400139e5b47
group: 3ac3e21100e473e57d9a1b26
id: 62b1a9d75e374e00112e3ca4
origin: 6238a3a27d792400139e5b47
serie: 3ac3e21100e473e57d9a1b26
time: '2022-06-21T11:21:59.415Z'
value: 71
variable: temperature
- data:
origin: 62308e38de51960019697e76
query: last_value
variables:
- temperature
result:
- device: 62308e38de51960019697e76
id: 62309cb173cb3b001a031db5
metadata:
old_value: '45'
origin: 62308e38de51960019697e76
time: '2022-03-15T14:03:29.476Z'
unit: C
value: '33'
variable: temperature
widget:
analysis_run: null
dashboard: 623c74a15a13360011803f3e
data:
- origin: 6238a3a27d792400139e5b47
query: last_value
variables:
- temperature
- origin: 62308e38de51960019697e76
query: last_value
variables:
- temperature
display:
header_buttons: []
show_units: true
show_variables: true
theme:
color:
background: hsla(332, 33%, 73%, 1)
button: hsla(112, 91%, 58%, 1)
dot: hsla(0, 97%, 48%, 1)
header: hsla(336, 81%, 51%, 1)
variables:
- origin: 6238a3a27d792400139e5b47
variable: temperature
- origin: 62308e38de51960019697e76
variable: temperature
id: 623c79da5a13360011819b1d
label: 'Display #1'
realtime: 'true'
resource: []
type: display
status: true
/dashboard/{dashboardID}/widget:
parameters:
- name: dashboardID
in: path
required: true
schema:
type: string
example: (Type a dashboard ID)
post:
tags:
- Widgets
summary: Create Widget
description: "Create a widget within a specific dashboard in your profile.\nEach widget has unique properties. To ensure accuracy, we recommend opening your Admin Developer Panel, navigating to the desired Dashboard, and copying the Widget's JSON structure directly. \n:::warning \nAfter you create a widget, it is not automatically added to the dashboard's Arrangement parameter. You must manually edit the dashboard arrangement to include the widget's position in the grid. \n:::\n"
operationId: createDashboardWidget
requestBody:
content:
application/json:
schema:
type: object
properties:
analysis_run:
type: string
example: Analysis to trigger when a button is pressed. Used by Form and Dynamic Table widgets.
dashboard:
type: string
description: Your Dashboard ID
data:
type: array
items:
type: object
description: Data that will be available to your widget.
display:
type: object
description: The display property of your widget. Each widget has it's unique properties.
id:
type: string
label:
type: string
example: Title Label of the Widget
realtime:
type: boolean
example: true
type:
type: string
example: The widget unique type.
examples:
Card Widget Example:
value:
analysis_run: null
display:
alias: Ice Cream
header_buttons:
- color: null
icon: ''
text: ''
trigger: widget
widget: null
help: You can edit this widget to add a message here
frame_settings:
shadow:
hide: false
header_visibility: show_always
theme:
color:
background: hsl(210, 12%, 12%)
header: hsl(210, 65%, 60%)
text: hsl(210, 20%, 92%)
show_variables: true
formula:
enable: false
unit_type: origin
fixed_unit: ''
apply_all_matching_formulas: false
number_format:
decimals: -1
show_thousand: false
max_points: 10
show_chart: true
show_unit: true
url: ''
variable: temperature
data:
- qty: 10
origin: 68c9baabb24379000ab1c8cc
variables:
- temperature
resource: []
id: 68c9bab8fe8818000a7ec597
label: Temperature
realtime: null
type: card
cache: null
responses:
'200':
description: ''
/dashboard/{dashboardID}/widget/{widgetID}/token:
parameters:
- name: dashboardID
in: path
required: true
schema:
type: string
example: (Type a dashboard ID)
- name: widgetID
in: path
required: true
schema:
type: string
example: (Type a widget ID)
get:
tags:
- Widgets
summary: Generate Token
description: "Generates a secure, public token for [embedding](/docs/tagoio/widgets/general/embedding-widgets-to-your-website) a specific widget from a dashboard. \nUse this token to display the widget in external applications or websites via the TagoIO embed service. \n\nExample embed URL: \n\n`https://embed.REGION.tago.io?widget=YOUR-WIDGET-ID&dashboard=YOUR-DASHBOARD-ID&token=YOUR-EMBED-TOKEN` \n\nThis endpoint is intended for scenarios where you want to share or display a widget outside of the TagoIO platform while maintaining access control.\n"
operationId: generateToken
responses:
'200':
description: Generating a token
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
widget_token:
type: string
example: ebe71a39-8f9f-4114-8bf3-6b3dcc19ad72
status:
type: boolean
example: true
examples:
Generating a token:
value:
result:
widget_token: ebe71a39-8f9f-4114-8bf3-6b3dcc19ad72
status: true
components:
securitySchemes:
Device-Token:
type: apiKey
description: A Device-Token that is unique to your device. Generate a token by accessing your Device's page.
name: Device-Token
in: header
x-example: 5e12345a-d70a-4e2d-b83d-5c0123456789
Network-Token:
type: apiKey
description: A Network Token that is unique to your Network. Access Integrations > Network > Tokens to generate a token for
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tago-io/refs/heads/main/openapi/tago-io-widgets-api-openapi.yml