Sepolo public API

REST API documentation for partners and developers.

A practical, JSON-based API for reading Sepolo organization data into Power BI, reporting tools and partner applications.

Download Postman collection View webhook events

Introduction

The Sepolo API is organized around versioned REST endpoints. Every response is JSON, every request is scoped to the organization that owns the API key, and list endpoints return a predictable data envelope for BI tools.

Base URL: https://api.sepolo.app

Current version: v1

Format: JSON over HTTPS

Authentication

Create the organization API key inside Sepolo under Profile, Configuration, API Key. Send it as an HTTP header on every request.

X-Sepolo-Api-Key: sep_live_your_api_key

The key can also be sent as a bearer token when a client cannot set custom headers.

Authorization: Bearer sep_live_your_api_key

List responses

List endpoints return data, nextCursor and hasMore. The current public endpoints return all records for the selected organization and date window. Cursor paging can be added later without changing the response envelope.

Errors

Errors use normal HTTP status codes. Authentication problems return 401, missing scopes return 403, validation errors return 400 and unexpected failures return 500 with a traceable error payload.

{
  "error": "forbidden",
  "message": "The API key does not include the appointments.read scope."
}

Endpoints

These endpoints are the first public API group for reporting and partner integrations.

GET/api/v1/me

Current integration

Returns the integration identity, organization id, granted scopes, version metadata and allowed data boundaries.

Return type

PublicApiMeResponse

Required scopes

public_api.read

Example request

curl https://api.sepolo.app/api/v1/me \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "organizationId": "7f2d3f0a-7c51-42cf-a06d-2c2df5f0c20b",
  "clientId": "sep_live_...",
  "clientName": "Partner API",
  "scopes": ["assets.read", "devices.read", "service_visits.read"],
  "version": "v1",
  "rateLimit": { "requestsPerMinute": null, "requestsPerDay": null },
  "allowedGroupIds": [],
  "allowedCustomerIds": []
}

GET/api/v1/assets

Assets

Lists organization assets for reporting, customer portals and integration sync jobs.

Return type

PublicApiPage<PublicApiAssetDto>

Required scopes

assets.read

Query parameters

updatedSincedate-timeOnly assets updated after this timestamp.

groupIdintegerOptional asset group filter.

customerIdstringOptional external customer id filter.

statusstringactive, inactive or all.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/assets \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/assets/{assetId}

Asset by id

Returns one asset if it belongs to the API key organization.

Return type

PublicApiAssetDto

Required scopes

assets.read

Example request

curl https://api.sepolo.app/api/v1/assets/{assetId} \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "assetId": "a33b5a5d-e55a-423d-9bdf-0bc2c61f7e63",
  "name": "Cooling line 4",
  "deviceId": "SEP-DEVICE-001",
  "isActive": true
}

GET/api/v1/assets/{assetId}/children

Asset children

Returns child assets for a parent asset.

Return type

PublicApiPage<PublicApiAssetDto>

Required scopes

assets.read

Query parameters

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/assets/{assetId}/children \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/devices

Devices

Lists devices owned by the organization.

Return type

PublicApiPage<PublicApiDeviceDto>

Required scopes

devices.read

Query parameters

updatedSincedate-timeOnly devices updated after this timestamp.

groupIdintegerOptional group filter.

statusstringOptional numeric device status filter.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/devices \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/devices/{deviceId}

Device by id

Returns one device if it belongs to the API key organization.

Return type

PublicApiDeviceDto

Required scopes

devices.read

Example request

curl https://api.sepolo.app/api/v1/devices/{deviceId} \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "deviceId": "SEP-DEVICE-001",
  "deviceName": "Cooling line sensor",
  "groupId": 12,
  "batteryPercentage": 92
}

GET/api/v1/devices/{deviceId}/telemetry

Device telemetry

Returns telemetry samples for a device. The from and to query parameters are required.

Return type

PublicApiPage<PublicApiTelemetryDto>

Required scopes

telemetry.read

Query parameters

fromdate-timeRequired start timestamp. fromUtc is also accepted.

todate-timeRequired end timestamp. toUtc is also accepted. Maximum window is 31 days.

metricsstringOptional comma-separated metric hint.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/devices/{deviceId}/telemetry \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/devices/{deviceId}/movements

Device movements

Returns movement windows for a device, including duration, current values and anomaly metadata.

Return type

PublicApiPage<PublicApiMovementDto>

Required scopes

movements.read

Query parameters

fromdate-timeRequired start timestamp. fromUtc is also accepted.

todate-timeRequired end timestamp. toUtc is also accepted.

minDurationSecondsintegerOptional minimum movement duration.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/devices/{deviceId}/movements \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/incidents

Incidents

Lists incidents for the organization.

Return type

PublicApiPage<PublicApiIncidentDto>

Required scopes

incidents.read

Query parameters

fromUtcdate-timeOptional start timestamp.

toUtcdate-timeOptional end timestamp.

deviceIdstringOptional device id filter.

stateintegerOptional incident state filter.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/incidents \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/service-reports

Service reports

Lists service reports for reporting and partner applications.

Return type

PublicApiPage<PublicApiServiceReportDto>

Required scopes

service_reports.read

Query parameters

fromUtcdate-timeOptional created-on start timestamp.

toUtcdate-timeOptional created-on end timestamp.

assetIduuidOptional asset filter.

deviceIdstringOptional device filter.

stateintegerOptional report state filter.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/service-reports \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/service-reports/{serviceReportId}

Service report by id

Returns one service report if it belongs to the API key organization.

Return type

PublicApiServiceReportDto

Required scopes

service_reports.read

Example request

curl https://api.sepolo.app/api/v1/service-reports/{serviceReportId} \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "serviceReportId": "5c722f76-5f0b-4c1b-875d-05a1d8cd47b5",
  "assetId": "a33b5a5d-e55a-423d-9bdf-0bc2c61f7e63",
  "stateText": "Completed"
}

POST/api/v1/service-reports

Create service report

Creates a service report for trusted integrations. This is not granted to normal read-only API keys.

Return type

PublicApiCreatedServiceReportResponse

Required scopes

service_reports.write

Example request

curl https://api.sepolo.app/api/v1/service-reports \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "serviceReportId": "5c722f76-5f0b-4c1b-875d-05a1d8cd47b5"
}

GET/api/v1/service-visits

Service visits

Returns service visit data for BI, partner portals and operational reporting.

Return type

PublicApiPage<PublicApiServiceVisitDto>

Required scopes

service_visits.read

Query parameters

fromUtcdate-timeOptional start of the service visit window.

toUtcdate-timeOptional end of the service visit window. Maximum window is 366 days.

Example request

curl https://api.sepolo.app/api/v1/service-visits \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/appointments

Appointments

Returns planned service appointments for calendars, reporting tools and planning integrations.

Return type

PublicApiPage<PublicApiAppointmentDto>

Required scopes

appointments.read

Query parameters

fromUtcdate-timeOptional start of the appointment window.

toUtcdate-timeOptional end of the appointment window. Maximum window is 366 days.

userIduuidOptional Sepolo user id filter.

Example request

curl https://api.sepolo.app/api/v1/appointments \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/customers

Customers

Lists customer directory records available to the organization.

Return type

PublicApiPage<PublicApiCustomerDto>

Required scopes

customers.read

Query parameters

externalSystemstringOptional ERP/source system filter.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/customers \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/vendors

Vendors

Lists all vendors available to the organization.

Return type

PublicApiPage<PublicApiVendorDto>

Required scopes

vendors.read

Example request

curl https://api.sepolo.app/api/v1/vendors \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/inventory/parts

Inventory parts

Lists machine parts and inventory items.

Return type

PublicApiPage<PublicApiInventoryPartDto>

Required scopes

inventory.read

Query parameters

vendorIduuidOptional vendor filter.

statusstringactive, inactive or all.

pageSizeintegerPage size, maximum 500.

cursorstringCursor returned by the previous page.

Example request

curl https://api.sepolo.app/api/v1/inventory/parts \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "data": [],
  "nextCursor": null,
  "hasMore": false
}

GET/api/v1/reporting/assets-summary

Assets summary

Returns asset counts and maintenance cost totals for dashboards.

Return type

PublicApiAssetsSummaryDto

Required scopes

reporting.read

Example request

curl https://api.sepolo.app/api/v1/reporting/assets-summary \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "totalAssets": 120,
  "activeAssets": 112,
  "inactiveAssets": 8,
  "withDevices": 98,
  "overdueService": 7,
  "totalMaintenanceCost": 420000
}

GET/api/v1/reporting/service-performance

Service performance

Returns visit counts and cost totals for a reporting window.

Return type

PublicApiServicePerformanceDto

Required scopes

reporting.read

Query parameters

fromUtcdate-timeOptional start timestamp.

toUtcdate-timeOptional end timestamp. Maximum window is 366 days.

Example request

curl https://api.sepolo.app/api/v1/reporting/service-performance \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

{
  "totalVisits": 42,
  "completedVisits": 35,
  "openVisits": 7,
  "estimatedCost": 91000,
  "actualCost": 97250
}

GET/api/v1/reporting/telemetry-daily

Telemetry daily

Returns daily telemetry aggregates for BI and reporting.

Return type

IReadOnlyList<PublicApiTelemetryDailyDto>

Required scopes

reporting.read

Query parameters

fromUtcdate-timeOptional start timestamp.

toUtcdate-timeOptional end timestamp. Maximum window is 366 days.

deviceIdstringOptional device id filter.

Example request

curl https://api.sepolo.app/api/v1/reporting/telemetry-daily \
  -H "X-Sepolo-Api-Key: sep_live_your_api_key"

Example response

[
  {
    "deviceId": "SEP-DEVICE-001",
    "date": "2026-05-13T00:00:00Z",
    "samples": 288,
    "averageTemperature": 18.4
  }
]