Skip to content
Ditio Developer Docs

External Excavator State

Full CRUD + bulk import for external excavator state data. This is the primary machine integration endpoint.

Endpoints

Section titled “Endpoints”
MethodRouteDescription
POSTapi/external-excavator-stateRegister a single state record
POSTapi/external-excavator-state/importBulk import state records
GETapi/external-excavator-state/latest-timestamp/{companyId}/{projectId}Get sync checkpoint
POSTapi/external-excavator-state/aggregated-data-per-stateQuery aggregated utilization

Base URL

Section titled “Base URL”

The Mass Transport API base URL is provided by your Ditio contact during onboarding; routes below are relative to it.

Authentication

Section titled “Authentication”

Requires a Bearer token with the masstransportapiv1 scope. See Authentication.

Register Single State

Section titled “Register Single State”
POST /api/external-excavator-state

Request Body

Section titled “Request Body”
{
  "companyId": "string",
  "projectId": "string",
  "machineId": "string",
  "state": "string",
  "startTime": "ISO 8601 datetime",
  "endTime": "ISO 8601 datetime"
}

Response

Section titled “Response”

201 Created on success.

Bulk Import

Section titled “Bulk Import”
POST /api/external-excavator-state/import

Request Body

Section titled “Request Body”

Array of state records (same schema as single registration).

Response

Section titled “Response”

201 Created on success.

Latest Timestamp (Sync Checkpoint)

Section titled “Latest Timestamp (Sync Checkpoint)”
GET /api/external-excavator-state/latest-timestamp/{companyId}/{projectId}

Returns the timestamp of the most recent record received for the given company and project. Use this to avoid sending duplicate data.

Aggregated Data Per State

Section titled “Aggregated Data Per State”
POST /api/external-excavator-state/aggregated-data-per-state

Query machine utilization statistics grouped by state type.

Section titled “Related”