TagoIO Network Ingest API

openapi: 3.1.0
info:
  title: TagoIO Access Management Network Ingest 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: Network Ingest
  description: Endpoints that act as a network using a Network Token (network-level permissions).
paths:
  /integration/network/resolve/{serieNumber}/{AuthorizationKey}:
    parameters:
    - name: serieNumber
      in: path
      required: true
      schema:
        type: string
      description: Device Serial Number registered at TagoIO
    - name: AuthorizationKey
      in: path
      required: true
      schema:
        type: string
      description: Authorization key for the profile, used to resolve the device token when multiple profiles may have the same serial number.
    get:
      tags:
      - Network Ingest
      summary: Find Device by Serial & Authorization Key
      description: "Retrieve a valid device token using the device's serial number and a profile authorization key.  \nThis endpoint is recommended when you need additional security or if your Network is available to multiple profiles, as it allows serial numbers to be duplicated across different profiles.  \nYou must have both a Network and a Network-Token to use this endpoint."
      operationId: getDeviceTokenWithSerialNumberAuthorization
      security:
      - Network-Token: []
      responses:
        '200':
          description: Successfully Token Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: <string>
                  status:
                    type: boolean
                    example: true
  /integration/network/resolve/{serieNumber}:
    parameters:
    - name: serieNumber
      in: path
      required: true
      schema:
        type: string
      description: Device Serial Number registered at TagoIO
    get:
      tags:
      - Network Ingest
      summary: Find Device by Serial
      description: "Get a valid device-token using token serial number only. It will match the serial in any profile.\n:::warning  \nIf the serial number is duplicated between different profiles, you will get the device-token only for the latest device created. See [Find Device with Authorization](/docs/api/get-device-token-with-serial-number-authorization) for multiple profiles support.  \n:::\nYou must have a Network and a Network-Token to use this query."
      operationId: getDeviceTokenWithSerialNumber
      security:
      - Network-Token: []
      responses:
        '200':
          description: got a valid token
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: <string>
                  status:
                    type: boolean
                    example: true
  /integration/network/{deviceID}/params:
    parameters:
    - name: deviceID
      in: path
      required: true
      schema:
        type: string
    post:
      tags:
      - Network Ingest
      summary: Edit Device Configuration Parameter
      description: 'Edit a device configuration parameter using the Network-token. You must already have the device ID to use this endpoint.

        This is useful when your Network integration requires configuration parameters for performing downlinks, or if your decoder benefits from configuration parameters for parsing data.

        :::info

        To obtain the **Device ID**, first resolve the device-token, then use the [Device Information](/docs/api/current-device-information) endpoint to retrieve detailed information about the device.

        :::'
      operationId: editDeviceConfigurationParameter
      security:
      - Network-Token: []
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    example: 6114b901cd09d0fa0013636afcc
                  key:
                    type: string
                    example: downlink_url
                  sent:
                    type: boolean
                    example: true
                  value:
                    type: string
                    example: https://mydownlink.url.io
              example:
              - id: 6114b901cd09d0fa0013636afcc
                key: downlink_url
                sent: true
                value: https://mydownlink.url.io
            examples:
              Edit Device Configuration Parameter:
                value:
                - id: 6114b901cd09d0fa0013636afcc
                  key: downlink_url
                  sent: true
                  value: https://mydownlink.url.io
      responses:
        '200':
          description: Edit the configuration parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: Device Configuration Parameter Updated
                  status:
                    type: boolean
                    example: true
  /integration/network/data:
    post:
      tags:
      - Network Ingest
      summary: Send Data using Network
      description: "Send data to TagoIO using the Network instead.\n\nThis endpoint allows the [Network Payload Parser](/docs/tagoio/devices/payload-parser/) to identify and redirect data to the correct device created using the Network associated with the Network Token and [Authorization Token](/docs/tagoio/integrations/general/authorization/).\n\nThe Network's Payload Parser is required to set the serial within the network parser. For example:\n\n``` javascript\n if (Array.isArray(payload)) {\n   const payload_received = payload.find(x => x.variable === \"payload\");\n   serial = payload_received?.metadata?.serial;\n }\n\n ```"
      operationId: sendDataUsingNetwork
      parameters:
      - $ref: '#/components/parameters/authorization_token'
      security:
      - Network-Token: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkDeviceData'
          text/plain:
            schema:
              type: string
              description: 'Arbitrary payload. Your [Network Payload Parser](/docs/tagoio/devices/payload-parser/) must normalize this text to the TagoIO array format accepted by application/json.

                '
            examples:
              Send Data using Network:
                value: 'Any format data that your Payload Parser can normalize to TagoIO format.

                  '
      responses:
        '200':
          description: Send Data
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    example: 1 Data Added
                  status:
                    type: boolean
                    example: true
components:
  parameters:
    authorization_token:
      name: authorization_token
      in: query
      required: true
      description: 'Authorization_Token

        '
      schema:
        type: string
        example: at72fb69a8dc714059b6cebee41693eb0
  schemas:
    NetworkDeviceData:
      type: object
      required:
      - variable
      properties:
        variable:
          type: string
          example: payload
        value:
          type: string
          description: Hexadecimal string payload
          example: 41BC7E1F2A
        metadata:
          type: object
          properties:
            serial:
              type: string
              description: Device serial number
              example: SN123456789
          additionalProperties: false
      description: Network device data format with payload and serial metadata.
  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 your Network.
      name: Token
      in: header
      x-DisplayName: Network-Token
      x-example: fd549ad2-813c-4d66-bf72-508e5b98afe3
    Profile-Token:
      type: apiKey
      description: A Profile token that is unique to your entire profile. Generate in your account settings.
      name: Profile-Token
      in: header
      x-example: a15ea5ea-dd2d-4c63-8945-92b54da4772a
x-tagGroups:
- name: Device Token (Device-level)
  tags:
  - Device Data
- name: Network Token (Network-level)
  tags:
  - Network Ingest
- name: Device Management
  tags:
  - Devices
  - Device Tokens
  - Configuration Param
  - Import/Export
  - Immutable Device
- name: Tago RUN
  tags:
  - Tago RUN
  - Users
  - Dictionary
  - Notifications
- name: Dashboards
  tags:
  - Dashboards
  - Widgets
- name: File(s) Management
  tags:
  - Files
  - Upload
- name: Profile
  tags:
  - Account
  - Profile
  - Statistics / Billing
- name: Entities
  tags:
  - Entity
  - Entity Data
- name: Resources
  tags:
  - Access Management