<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.

This guide is for users with the Manager role (corporate_manager). It covers finding your traps, downloading their images, reading catches and measurements, and managing your organization. The API uses the word corporation for an organization and orchard for a trap group.

Full API reference: Swagger.

Environments
Authentication and token refresh
Response formats, dates, and IDs
Devices
Images
Catches and exports
Measurements and network diagnostics
Locations
Pests and crops
Trap groups
Organizations and users
Other useful manager features
Troubleshooting

Environments

Environment	Base URL	Configured access-token lifetime	Configured refresh-token lifetime
Production	`https://dashboard.scoutlabs.ag`	5 hours	7 days
Sandbox	`https://sandbox.dashboard.scoutlabs.ag`	5 days	1 day

The JWT's exp claim gives its actual expiry. In sandbox, refresh tokens can expire before access tokens.

Sandbox data can be outdated and image files may be unavailable. The examples use production URLs; use the sandbox base URL for integration testing.

Authentication and token refresh

Supply a username or email address in username:

Example request:

curl --request POST "<https://dashboard.scoutlabs.ag/api/auth/>" \
  --header "Content-Type: application/json" \
  --data '{"username":"[email protected]","password":"EXAMPLE-PASSWORD"}'

Example request body:

{
  "username": "[email protected]",
  "password": "EXAMPLE-PASSWORD"
}

Example response — 200 OK:

{
  "refresh": "EXAMPLE-REFRESH-TOKEN",
  "access": "EXAMPLE-ACCESS-TOKEN"
}

Send the access token as Authorization: Bearer EXAMPLE-ACCESS-TOKEN. Refresh it with:

Example request:

curl --request POST "<https://dashboard.scoutlabs.ag/api/auth/refresh/>" \
  --header "Content-Type: application/json" \
  --data '{"refresh":"EXAMPLE-REFRESH-TOKEN"}'

Example request body:

{
  "refresh": "EXAMPLE-REFRESH-TOKEN"
}

Example response — 200 OK:

{
  "access": "EXAMPLE-NEW-ACCESS-TOKEN",
  "refresh": "EXAMPLE-RETURNED-REFRESH-TOKEN"
}

Store both returned tokens. If the refresh token is invalid or expired, sign in again.

The JWT includes your user_id, role (user.type), and expiry (exp). Retrieve your account with GET /api/users/{user_id}/; its corporation identifies your home organization.

Response formats, dates, and IDs

Pagination

Most lists return meta and data; detail requests return one object.

{
  "meta": {
    "next": null,
    "previous": null,
    "count": 1,
    "page": 1,
    "page_size": 20
  },
  "data": [
    {
      "id": "EXAMPLE-DEVICE-UUID",
      "name": "North field"
    }
  ]
}

| --- | --- | --- |

Response examples below show selected fields and omit the common meta object. Exports use different formats. Filters vary by endpoint; unknown filters may be ignored.

Dates and missing values

Most device-data timestamps, including created_at, updated_at, upload_at, and aggregate timestamp values, are Unix seconds, sometimes with a fractional part. Use seconds, not milliseconds, in timestamp filters.

Some fields use calendar dates or ISO 8601 instead:

| --- | --- |

The backend's default timezone is UTC. Use explicit timezone offsets for ISO 8601 inputs. A device's timezone identifies its local timezone, such as Europe/Budapest.

The example reporting range is 2026-10-01 through 2026-10-07 UTC (1790812800–1791417599). Biofix, degree-day model/stage, route, status, and tag record timestamps use ISO 8601.

A null measurement or catch count means unavailable data; it is different from zero catches. Coordinate values are returned as decimal strings on the location endpoints.

Identifiers

| --- | --- |

Devices

Assign a trap to your organization

Sign in and get your organization's UUID from your user record's corporation field; see Authentication and token refresh. For a sub-organization, use its UUID from Organizations and users.

Find the device by MAC or IMEI and take the returned device_id.
Assign it to your organization by including that UUID in devices_to_add on the target organization.

The assignment is complete, and the trap appears in your device list. For field setup, configure its pest, crop, timezone, and location, and see Installation, replacement, and archiving for setup status. Assignment alone does not guarantee an installed status.

List and retrieve