<aside> 📜 TABLE OF CONTENTS

• Introduction

📔 Guides

• The broken logic of trap density (start here)
• Trap assembly guide (video + steps)
• Installation guides for different crops
• Installation guides for different pests
• Overwintering guide

🪤 Using your traps and apps

• Mobile app overview
• Web app overview
• Regular maintenance

🆘 Problems? Get help

• Troubleshooting
• Mini status lights meaning
• Customer support

🧑‍💻 Tech stuff

• API documentation
• Changelog

💡 Other important info

• Privacy and security
• FAQ </aside>

API Documentation 💻

This API documentation is intended for developers who want to integrate scoutlabs data into other applications. This section provides details on how to use the API, including environments, authentication, available endpoints, and request and response examples.

Environments

TEST environment

• URL: https://sandbox.dashboard.scoutlabs.ag
• This environment contains data from the PRODUCTION environment and is updated periodically. Please exercise caution, as the data may be outdated. The images are not transferred from the production server, so they will not load. If you need the images for any reason, please use the production environment.
• Access token expiry: 5 days

PRODUCTION environment:

• URL: https://dashboard.scoutlabs.ag
• Be careful when using the production environment, especially when using an admin account.
• Accesstoken expiry: 5 hours

Authentication endpoint

API Endpoint: POST /api/auth/

Description:

This endpoint allows you to authenticate with the backend system. Authentication is required to access additional functionalities. Upon successful authentication, you will receive an access token and a refresh token. The access token grants you permission to use other endpoints.

Note: We currently do not use the refresh token.

Example:

curl 
    --request POST
    --url <https://dashboard.scoutlabs.ag/api/auth/>
    --data '{
        "username": "clientusername",
        "password": "clientpassword"
    }'

Request body:

{
    "username": "clientusername", // username or email
    "password": "clientpassword" // paswword
}

Example response:

{
    "refresh": "exampleaccesstoken", // Not in use yet
    "access": "examplerefreshtoken" // Can be used until it is expire (5h)
}

Data endpoints

General description:

The data endpoints can be used to retrieve data, including device information, measurements, catch records, statistics, and any other data stored in our database.

List endpoints general description:

We have list endpoints that support pagination. All list endpoints will return two fields: 'meta' and 'data'. The 'meta' field contains pagination-related information such as 'page', 'page_size', 'count', 'next', and 'previous'. The 'next' and 'previous' fields can also be used to paginate through the endpoint. If 'next' or 'previous' is null, it means there are no more pages in that direction. The 'data' field contains an array with all the results. Maximum page size: 100

Single endpoints general description:

The single endpoints will return a single object, containing all the fields for the specific device, measurement, and so on.

List endpoints general response format example:

{
  "meta": {
      "next": "/api/devices/?page=3&page_size=20", // null, if there is no more page
      "previous": "/api/devices/?page=1&page_size=20", // null, if there is no more page
      "count": 420, // total size of elements
      "page": 2, // Current page
      "page_size": 20 // Page size, maximum 100
  },
  "data": [
      {
      ...
      }
  ]
}

Device list

API Endpoint: GET /api/devices/

Description:

The Devices endpoint is used for retrieving data specifically related to trap devices. If no filters are applied, you can paginate through all the devices assigned to the logged-in user.

Note: Non-admin users can only access devices that are added to their profile.

Example:

curl 
    --request GET
    --url '<https://dashboard.scoutlabs.ag/api/devices/>'
    --header 'Authorization: Bearer EXAMPLEACCESSTOKEN'

Request body:

No request body

Authorization header:

'Authorization: Bearer EXAMPLEACCESSTOKEN'

Querystring parameters:

page: 1 // Requested page
page_size: 20 // requested page size, maximum 100
mac: searched_device_mac // MAC addresss of the device to filter
imei: searched_device_imei // IMEI adress of the device to filter
ordering: smapp_id // The result can be ordered for different fields
statuses: working,maintenance_needed,not_working,not_validated,turned_off,not_installed,shipped_back
status__in: working,cleaning_needed,missing_sticky_sheet,low_battery_or_draining,camera_or_trap_broken,maintenance_needed,no_picture_today,no_picture_for_multiple_days,picture_problem,stopped_working,wrong_coordinates,validation_needed,not_validated,end_of_season,turned_off,recalled,not_installed,spare,uninstalled,planned_to_be_installed,shipped_back
active: true // Is the trap active or not
search: search_string // Filters devices related to the 'search_string'

Searchable fields:

We can use the ‘search’ parameter in the request to search across different fields. When we use the ‘search’ parameter, it will filter through all the fields mentioned below.

name // Device name
smapp_id // Device SMP-ID: (e.g. SMP-0000)
imei // Device IMEI address: (e.g. 000000000000000)
mac // Device MAC address: (e.g. F0F0F0F0F0F0)
type // Device type: miniv2, premium ...
country // Country of the device
city // City of the device
timezone // Timezone of the device
comment // Comments related to the device
pest_name // Pest name monitored by the device
crop_name // Crop name monitored by the device
config_name // Name of the config what the device uses
firmware_name // The name of the firmware wich active on the device
corporate_name // The name of the corporation
commission_status_text // The text of the comission status

Fields available for ordering:

We can use the ‘ordering’ parameter in the request to sort the results by different fields. All the fields mentioned below can be used for ordering.

type // Type of the device
name // Name of the device
smapp_id // Unique SMP id of the device in the system
imei // Device’s IMEI number
mac // Device’s MAC address
imsi // Device’s IMSI number
iccid // SIM card’s ICCID
country // Country of the device
city // City of the device
timezone // Timezone of the device’s location
created_at // Record creation timestamp
updated_at // Last updated timestamp
comment // Additional notes or comments
status_needs_approval // Status flag requiring approval

Example response:

{
    "meta": {
        "next": null,
        "previous": null,
        "count": 2,
        "page": 1,
        "page_size": 20
    },
    "data": [
        {
            "id": "EXAMPLE-UUID", // Device id
            "created_at": 1678040393.282992,
            "updated_at": 1726491205.339389,
            "type": "premium", // Device type: miniv2, premium ...
            "name": "Device name", // Name of the device, given by the user
            "smapp_id": "SMP-0000", // Auto generated SMP id
            "imei": "000000000000000", // Unique device IMEI
            "mac": "000000000000", // Unique device MAC
            "country": "FR",
            "city": "TEST",
            "timezone": "Europe/Budapest",
            "last_image": "EXAMPLE-UUID", // Last uploaded image id
            "last_geo_point": "EXAMPLE-UUID", // Last uploaded geo point id
            "most_relevant_geo_point": { // Mostly the same what we can get with the 'last_geo_point'
                "latitude": "EXAMPLE-LATITUDE",
                "longitude": "EXAMPLE-LONGITUDE"
            },
            "last_measurement": "EXAMPLE-UUID", // Last uploaded measurement id
            "last_network_diagnostic": "EXAMPLE-UUID", // Last uploaded network diagnostic id
            "last_summed_detection_count": 71,
            "last_summed_detection_count_delta": 5,
            "current_pest": "EXAMPLE-UUID", // Currently monitored pest id
            "current_crop": "EXAMPLE-UUID", // Currently monitored crop id
            "pest_name": "EXAMPLE-PEST-NAME", // Currently monitored pest name
            "crop_name": "EXAMPLE-CROP", // Currently monitored crop name
            "status": "spare", // Device current status
            "status_general": "not_installed", // Simplified device status
            "device_image": true,
            "lure_days_life_remaining": null, // How many days remaining for the lure
            "lure_type": "", // User specified lure type
            "lure_days_life_span": null, // How long the lure can be used
            "lure_last_replaced": null, // When was the lure last time replaced
            "fullness_level": 0.6770755346748883, // Sticky sheet fullness level
            "requires_cleaning": true // Based on a threashold is the sheet should be changed
        },
    ]
}

Good to know:

Most of the fields returned by this endpoint contain UUIDs, which can be used to retrieve specific data such as crop, configuration, pest information, and so on.

Single device

Description:

When we have the UUID of a specific device, we can retrieve data for that device only. This applies to any other endpoints as well. To do this, the UUID must be included in the request URL, and only the data for that specific device will be returned.

Example:

curl 
    --request GET
    --url '<https://dashboard.scoutlabs.ag/api/devices/EXAMPLE-DEVICE-UUID/>'
    --header 'Authorization: Bearer EXAMPLEACCESSTOKEN'

Authorization header:

'Authorization: Bearer EXAMPLEACCESSTOKEN'

Example response:

{
		"id": "EXAMPLE-UUID", // Device id
		"created_at": 1678040393.282992,
		"updated_at": 1726491205.339389,
		"type": "premium", // Device type: miniv2, premium ...
		"name": "Device name", // Name of the device, given by the user
		"smapp_id": "SMP-0000", // Auto generated SMP id
		"imei": "000000000000000", // Unique device IMEI
		"mac": "000000000000", // Unique device MAC
		"country": "FR",
		"city": "TEST",
		"timezone": "Europe/Budapest",
		"last_image": "EXAMPLE-UUID", // Last uploaded image id
		"last_geo_point": "EXAMPLE-UUID", // Last uploaded geo point id
		"most_relevant_geo_point": { // Mostly the same what we can get with the 'last_geo_point'
		    "latitude": "EXAMPLE-LATITUDE",
		    "longitude": "EXAMPLE-LONGITUDE"
		},
		"last_measurement": "EXAMPLE-UUID", // Last uploaded measurement id
		"last_network_diagnostic": "EXAMPLE-UUID", // Last uploaded network diagnostic id
		"last_summed_detection_count": 71,
		"last_summed_detection_count_delta": 5,
		"current_pest": "EXAMPLE-UUID", // Currently monitored pest id
		"current_crop": "EXAMPLE-UUID", // Currently monitored crop id
		"pest_name": "EXAMPLE-PEST-NAME", // Currently monitored pest name
		"crop_name": "EXAMPLE-CROP", // Currently monitored crop name
		"status": "spare", // Device current status
		"status_general": "not_installed", // Simplified device status
		"device_image": true,
		"lure_days_life_remaining": null, // How many days remaining for the lure
		"lure_type": "", // User specified lure type
		"lure_days_life_span": null, // How long the lure can be used
		"lure_last_replaced": null, // When was the lure last time replaced
		"fullness_level": 0.6770755346748883, // Sticky sheet fullness level
		"requires_cleaning": true // Based on a threashold is the sheet should be changed
}

Updatable fields:

We can patch this endpoint to update certain device fields.

{
    "name": "EXAMPLE-DEVICE-NAME", // Simple device name
    "target_pest": "EXAMPLE-TARGET-PEST-UUID", // Most important, 
    // the AI will need this to what to search for
    "target_crop": "EXAMPLE-TARGET-CROP-UUID"
}

User management

Description:

This endpoint will return a list of users if the requester is an admin. Otherwise, it will return only the signed-in user's data, including their UUID and their corporation's UUID, which can later be used to assign a device to the given corporation.

Example:

curl 
    --request GET
    --url '<https://dashboard.scoutlabs.ag/api/users/>'
    --header 'Authorization: Bearer EXAMPLEACCESSTOKEN'

Authorization header:

'Authorization: Bearer EXAMPLEACCESSTOKEN'