<aside> 📜 TABLE OF CONTENTS

Introduction

📔 Guides

🪤 Using your traps and apps

🆘 Problems? Get help

🧑‍💻 Tech stuff

💡 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://dev.dashboard.smapplab.com
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.smapplab.com
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.smapplab.com/api/auth/>
    --data '{
        "username": "clientusername",
        "password": "clientpassword"
    }'

Request body:

{
    "username": "clientusername",
    "password": "clientpassword"
}

Example response:

{
    "refresh": "exampleaccesstoken",
    "access": "examplerefreshtoken"
}

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,
      "page_size": 20
  },
  "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.smapplab.com/api/devices/>'
    --header 'Authorization: Bearer EXAMPLEACCESSTOKEN'

Request body:

No request body

Authorization header:

'Authorization: Bearer EXAMPLEACCESSTOKEN'

Querystring parameters:

page: 1
page_size: 20
mac: searched_device_mac
imei: searched_device_imei
ordering: smapp_id
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

Example response:

{
    "meta": {
        "next": null,
        "previous": null,
        "count": 2,
        "page": 1,
        "page_size": 20
    },
    "data": [
        {
            "id": "EXAMPLE-UUID",
            "created_at": 1678040393.282992,
            "updated_at": 1726491205.339389,
            "type": "premium",
            "name": "SMP-0000",
            "smapp_id": "SMP-0000",
            "imei": "000000000000000",
            "mac": "000000000000",
            "country": "FR",
            "city": "TEST",
            "timezone": "Europe/Budapest",
            "last_image": "EXAMPLE-UUID",
            "last_geo_point": "EXAMPLE-UUID",
            "most_relevant_geo_point": {
                "latitude": "EXAMPLE-LATITUDE",
                "longitude": "EXAMPLE-LONGITUDE"
            },
            "last_measurement": "EXAMPLE-UUID",
            "last_network_diagnostic": "EXAMPLE-UUID",
            "last_summed_detection_count": 71,
            "last_summed_detection_count_delta": 5,
            "current_pest": "EXAMPLE-UUID",
            "current_crop": "EXAMPLE-UUID",
            "status": "spare",
            "status_general": "not_installed",
            "device_image": true
        },
    ]
}

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.smapplab.com/api/devices/EXAMPLE-DEVICE-UUID/>'
    --header 'Authorization: Bearer EXAMPLEACCESSTOKEN'

Authorization header:

'Authorization: Bearer EXAMPLEACCESSTOKEN'

Example response:

{
    "id": "EXAMPLE-UUID",
    "created_at": 1678040393.282992,
    "updated_at": 1726491205.339389,
    "type": "premium",
    "name": "SMP-0000",
    "smapp_id": "SMP-0000",
    "imei": "000000000000000",
    "mac": "000000000000",
    "country": "FR",
    "city": "TEST",
    "timezone": "Europe/Budapest",
    "last_image": "EXAMPLE-UUID",
    "last_geo_point": "EXAMPLE-UUID",
    "most_relevant_geo_point": {
        "latitude": "EXAMPLE-LATITUDE",
        "longitude": "EXAMPLE-LONGITUDE"
    },
    "last_measurement": "EXAMPLE-UUID",
    "last_network_diagnostic": "EXAMPLE-UUID",
    "last_summed_detection_count": 71,
    "last_summed_detection_count_delta": 5,
    "current_pest": "EXAMPLE-UUID",
    "current_crop": "EXAMPLE-UUID",
    "status": "spare",
    "status_general": "not_installed",
    "device_image": true
}

User information

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.smapplab.com/api/users/>'
    --header 'Authorization: Bearer EXAMPLEACCESSTOKEN'

Authorization header:

'Authorization: Bearer EXAMPLEACCESSTOKEN'

Example response:

{
    "meta": {
        "next": null,
        "previous": null,
        "count": 1,
        "page": 1,
        "page_size": 20
    },
    "data": [
        {
            "id": "EXAMPLE-UUID",
            "username": "EXAMPLE-USERNAME",
            "first_name": "",
            "last_name": "",
            "email": "EXAMPLE-EMAIL",
            "type": "corporate",
            "corporation": "EXAMPLE-UUID",
            "date_joined": 1724424462.957227,
            "last_login": 1726820709.671305
        }
    ]
}

Pests

API Endpoint: GET /api/pests

Description:

The Pest endpoint is used for retrieving detailed pest data by pest ID. It returns pests that can be assigned to traps. It does not return counts or statistics.

Example:

curl 
    --request GET
    --url '<https://dashboard.smapplab.com/api/pests/>'
    --header 'Authorization: Bearer EXAMPLEACCESSTOKEN'