{ "openapi": "3.1.1", "info": { "title": "Haloniq Developer API", "description": "## Overview\nThe Haloniq Developer API is a REST API for partner integrations over your fleet, telematics, media and streaming data. Responses use `snake_case` JSON; collections are wrapped in a `{ data, next_cursor, has_more }` envelope and paginated with an opaque `cursor`.\n\n## Authentication\nAll endpoints require an OAuth2 **client-credentials** bearer token. Each endpoint requires a single scope (see `security`). Requests for an organization outside your tenant return `403`.\n\n## Errors\nErrors are returned as RFC 7807 `application/problem+json` and always carry a stable, machine-readable `code` (for example `device.capability_missing`).\n\n## Idempotency\nCommand POSTs (video, device commands, streaming starts) require an `Idempotency-Key` header; replaying the same key with the same body returns the original result, a different body returns `422 idempotency.conflict`.\n\n## Webhooks\nOutbound events are delivered as CloudEvents 1.0 messages — see the `webhooks` section.\n\n## Regions\nEach region has its own base URL and token endpoint, and a token is accepted only by the region that issued it. This document describes Europe (EU); the other regions serve the same contract.\n\n| Region | API base URL | Token URL |\n| --- | --- | --- |\n| Europe (EU) | `https://developer.haloniq.com` | `https://auth.eu.haloniq.com/connect/token` |\n| United States (US) | `https://developer.us.haloniq.com` | `https://auth.us.haloniq.com/connect/token` |\n| Canada (CA) | `https://developer.ca.haloniq.com` | `https://auth.ca.haloniq.com/connect/token` |", "contact": { "name": "Haloniq Developer Support", "url": "https://developer.haloniq.com/", "email": "support@haloniq.com" }, "license": { "name": "Proprietary — Haloniq", "url": "https://haloniq.com/terms" }, "version": "1.0.0", "summary": "Programmatic access to Haloniq fleet, telematics, video and webhook resources." }, "servers": [ { "url": "https://developer.haloniq.com", "description": "Haloniq Developer API, Europe (EU)" } ], "paths": { "/v1/devices/{id}/assignment": { "put": { "tags": [ "Devices" ], "summary": "Assign a device to a vehicle", "description": "Assigns the device to a vehicle within the caller's tenant and returns the updated device.\n\n**Required scope:** `thirdparty.api.devices_write`", "operationId": "put_v1_devices_id_guid_assignment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignDeviceVehicleCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.devices_write" ] } ] }, "delete": { "tags": [ "Devices" ], "summary": "Unassign a device from its vehicle", "description": "Clears the device's vehicle assignment. Idempotent — returns 204 whether or not it was assigned.\n\n**Required scope:** `thirdparty.api.devices_write`", "operationId": "delete_v1_devices_id_guid_assignment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.devices_write" ] } ] } }, "/v1/devices/{hardwareId}/commands/reboot": { "post": { "tags": [ "Devices" ], "summary": "Enqueue a reboot command for a device", "description": "Queues a reboot for the device (202 Accepted). Requires an `Idempotency-Key` header. 422 `device.capability_missing` when the device cannot be rebooted; 422 `idempotency.conflict` when a key is reused with a different body.\n\n**Required scope:** `thirdparty.api.device_commands_reboot`", "operationId": "post_v1_devices_hardwareid_commands_reboot", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Client-generated idempotency key. Replaying the same key with the same body returns the original result; reusing it with a different body returns `422 idempotency.conflict`.", "required": true, "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCommandResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.device_commands_reboot" ] } ] } }, "/v1/devices/{hardwareId}/commands/wake-up": { "post": { "tags": [ "Devices" ], "summary": "Enqueue a wake-up command for a device", "description": "Queues a wake-up for the device (202 Accepted). Requires an `Idempotency-Key` header. 422 `device.capability_missing` when the device cannot be woken; 422 `idempotency.conflict` when a key is reused with a different body.\n\n**Required scope:** `thirdparty.api.device_commands_wake_up`", "operationId": "post_v1_devices_hardwareid_commands_wake_up", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Client-generated idempotency key. Replaying the same key with the same body returns the original result; reusing it with a different body returns `422 idempotency.conflict`.", "required": true, "schema": { "maxLength": 200, "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCommandResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.device_commands_wake_up" ] } ] } }, "/v1/devices": { "get": { "tags": [ "Devices" ], "summary": "Search devices", "description": "Lists devices visible to the caller, optionally filtered by organization, fleet or hardware id. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.devices_read`", "operationId": "get_v1_devices", "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "fleet_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "hardware_id", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfDeviceModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.devices_read" ] } ] } }, "/v1/devices/{id}": { "get": { "tags": [ "Devices" ], "summary": "Get device by id", "description": "Retrieves a single device master record by its identifier.\n\n**Required scope:** `thirdparty.api.devices_read`", "operationId": "get_v1_devices_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.devices_read" ] } ] } }, "/v1/devices/{hardwareId}/events": { "get": { "tags": [ "Devices" ], "summary": "Search a device's events", "description": "Lists a device's telematics events over a date window, optionally filtered by type or accident/important flags. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.devices_read`", "operationId": "get_v1_devices_hardwareid_events", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "event_types", "in": "query", "schema": { "type": "string" } }, { "name": "is_accident", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_important", "in": "query", "schema": { "type": "boolean" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfDeviceEventSummaryModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.devices_read" ] } ] } }, "/v1/devices/{hardwareId}/last-reported": { "get": { "tags": [ "Devices" ], "summary": "Get a device's last reported state", "description": "Returns the device's most recently reported telemetry state. 404 when the device has never reported.\n\n**Required scope:** `thirdparty.api.devices_read`", "operationId": "get_v1_devices_hardwareid_last_reported", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLastReportedModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.devices_read" ] } ] } }, "/v1/devices/{hardwareId}/media": { "get": { "tags": [ "Devices" ], "summary": "Search a device's media", "description": "Lists a device's media items over a date window, with SAS-signed download URLs. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.devices_read`", "operationId": "get_v1_devices_hardwareid_media", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfDeviceMediaModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.devices_read" ] } ] } }, "/v1/devices/{hardwareId}/last-position": { "get": { "tags": [ "Devices" ], "summary": "Get a device's last live position", "description": "Returns the device's last known live position enriched from the live store. 404 when no live position is available.\n\n**Required scope:** `thirdparty.api.live_positions_read`", "operationId": "get_v1_devices_hardwareid_last_position", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLastPositionModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.live_positions_read" ] } ] } }, "/v1/drivers": { "get": { "tags": [ "Drivers" ], "summary": "Search drivers", "description": "Lists drivers visible to the caller, optionally filtered by organization or fleet. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.drivers_read`", "operationId": "get_v1_drivers", "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "fleet_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfDriverModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.drivers_read" ] } ] }, "post": { "tags": [ "Drivers" ], "summary": "Create driver", "description": "Creates a driver in an organization/fleet within the caller's tenant. Returns the created resource with a Location header.\n\n**Required scope:** `thirdparty.api.drivers_write`", "operationId": "post_v1_drivers", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDriverCommand" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.drivers_write" ] } ] } }, "/v1/drivers/{id}": { "get": { "tags": [ "Drivers" ], "summary": "Get driver by id", "description": "Retrieves a single driver by its identifier.\n\n**Required scope:** `thirdparty.api.drivers_read`", "operationId": "get_v1_drivers_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.drivers_read" ] } ] }, "put": { "tags": [ "Drivers" ], "summary": "Update driver", "description": "Updates an existing driver's mutable attributes.\n\n**Required scope:** `thirdparty.api.drivers_write`", "operationId": "put_v1_drivers_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDriverCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriverModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.drivers_write" ] } ] } }, "/v1/events": { "get": { "tags": [ "Events" ], "summary": "Search events", "description": "Searches telematics events. At least one narrowing filter (`hardware_id`, `fleet_ids` or `vehicle_ids`) plus a date window is required, otherwise 400. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.events_read`", "operationId": "get_v1_events", "parameters": [ { "name": "hardware_id", "in": "query", "schema": { "type": "string" } }, { "name": "fleet_ids", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "vehicle_ids", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "event_types", "in": "query", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfEventListItemModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.events_read" ] } ] } }, "/v1/events/{eventId}": { "get": { "tags": [ "Events" ], "summary": "Get event by id", "description": "Retrieves a single event by its opaque composite `event_id` (base64url of `hardware_id | event_id`).\n\n**Required scope:** `thirdparty.api.events_read`", "operationId": "get_v1_events_eventid", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.events_read" ] } ] } }, "/v1/events/{eventId}/g-sensor-data": { "get": { "tags": [ "Events" ], "summary": "Get the G-sensor trace of an event", "description": "Returns the full-resolution G-sensor trace recorded around the event as JSON (`format_version` 1): event metadata, accelerometer samples and GPS points. 404 when the event is not visible to the caller, has no trace, or the trace is no longer stored (for example removed by retention).\n\n**Required scope:** `thirdparty.api.events_read`", "operationId": "get_v1_events_eventid_g_sensor_data", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The full-resolution G-sensor trace recorded around the event (`format_version` 1, snake_case, accelerometer values in mG).", "content": { "application/json": { "schema": { "type": "object", "description": "G-sensor trace document: `format_version`; `metadata` (`event_id`, `hardware_id`, `organization_id`, `fleet_id`, `vehicle_id` and `trigger_utc`; `fleet_id` and `vehicle_id` are null when the device has none); `accelerometer` (`unit` mG, `sample_rate_hz` and `samples[]` with `offset_ms` relative to the trigger and device-axis `x_axis`, `y_axis`, `z_axis` values in mG, gravity included; sub-second timing is derived from the sample rate); and `gps[]` (lower-rate points with `utc_timestamp`, `offset_ms`, `latitude`, `longitude` and `speed_kmh`; an empty array when the device had no valid GPS fix)." } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.events_read" ] } ] } }, "/v1/events/{eventId}/media": { "get": { "tags": [ "Events" ], "summary": "Get media for an event", "description": "Lists the media attached to an event, each with a SAS-signed download URL.\n\n**Required scope:** `thirdparty.api.events_read`", "operationId": "get_v1_events_eventid_media", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfEventMediaModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.events_read" ] } ] } }, "/v1/fleets": { "get": { "tags": [ "Fleets" ], "summary": "Search fleets", "description": "Lists fleets visible to the caller, optionally filtered by organization. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.fleets_read`", "operationId": "get_v1_fleets", "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfFleetModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.fleets_read" ] } ] }, "post": { "tags": [ "Fleets" ], "summary": "Create fleet", "description": "Creates a fleet in an organization within the caller's tenant. Returns the created resource with a Location header.\n\n**Required scope:** `thirdparty.api.fleets_write`", "operationId": "post_v1_fleets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFleetCommand" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FleetModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.fleets_write" ] } ] } }, "/v1/fleets/{id}": { "get": { "tags": [ "Fleets" ], "summary": "Get fleet by id", "description": "Retrieves a single fleet by its identifier.\n\n**Required scope:** `thirdparty.api.fleets_read`", "operationId": "get_v1_fleets_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FleetModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.fleets_read" ] } ] }, "put": { "tags": [ "Fleets" ], "summary": "Update fleet", "description": "Updates an existing fleet's mutable attributes.\n\n**Required scope:** `thirdparty.api.fleets_write`", "operationId": "put_v1_fleets_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFleetCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FleetModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.fleets_write" ] } ] } }, "/v1/journeys": { "get": { "tags": [ "Journeys" ], "summary": "Search journeys", "description": "Searches journeys over a date window for a vehicle, fleet and device. `hardware_id`, `vehicle_id`, `fleet_id`, `date_from` and `date_to` are all required, otherwise 400. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.journeys_read`", "operationId": "get_v1_journeys", "parameters": [ { "name": "vehicle_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fleet_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "hardware_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "date_to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "driver_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfJourneyModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.journeys_read" ] } ] } }, "/v1/journeys/{id}": { "get": { "tags": [ "Journeys" ], "summary": "Get journey by id", "description": "Retrieves a single journey by its identifier (`{yyyyMMddTHHmmssZ}-{hardwareId}`), including geometry.\n\n**Required scope:** `thirdparty.api.journeys_read`", "operationId": "get_v1_journeys_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JourneyModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.journeys_read" ] } ] } }, "/v1/live-positions": { "get": { "tags": [ "Live Positions" ], "summary": "Search live vehicle positions", "description": "Returns the latest live position for vehicles, optionally filtered by fleet. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.live_positions_read`", "operationId": "get_v1_live_positions", "parameters": [ { "name": "fleet_ids", "in": "query", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfLivePositionModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.live_positions_read" ] } ] } }, "/v1/me": { "get": { "tags": [ "Meta" ], "summary": "Token introspection", "description": "Returns the calling client's id, organization and granted scopes.", "operationId": "get_v1_me", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" }, "example": { "client_id": "acme-integration", "org_id": "0a6f6d1e-1c2b-4a5d-8e3f-9b7c6d5e4f30", "scopes": [ "thirdparty.api.fleets_read", "thirdparty.api.vehicles_read", "thirdparty.api.video_requests_write" ] } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ ] } ] } }, "/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "Search organizations", "description": "Lists the organizations visible to the caller (own tenant and its descendants), optionally filtered by parent. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.organizations_read`", "operationId": "get_v1_organizations", "parameters": [ { "name": "parent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfOrganizationModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.organizations_read" ] } ] } }, "/v1/organizations/{id}": { "get": { "tags": [ "Organizations" ], "summary": "Get organization by id", "description": "Retrieves a single organization by its identifier; only organizations within the caller's tenant are visible.\n\n**Required scope:** `thirdparty.api.organizations_read`", "operationId": "get_v1_organizations_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.organizations_read" ] } ] } }, "/v1/devices/{hardwareId}/live-stream": { "post": { "tags": [ "Streaming" ], "summary": "Start a live HLS stream for a device", "description": "Starts a live HLS stream and returns per-channel `.m3u8` URLs. Requires an `Idempotency-Key` header. Streamax devices only; unsupported devices return 422.\n\n**Required scope:** `thirdparty.api.live_streams_write`", "operationId": "post_v1_devices_hardwareid_live_stream", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Client-generated idempotency key. Replaying the same key with the same body returns the original result; reusing it with a different body returns `422 idempotency.conflict`.", "required": true, "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartLiveStreamCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveStreamResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.live_streams_write" ] } ] } }, "/v1/devices/{hardwareId}/live-stream/stop": { "post": { "tags": [ "Streaming" ], "summary": "Stop a device's live stream", "description": "Stops the device's live stream. The session is managed by hardware id (no session id). Returns 204.\n\n**Required scope:** `thirdparty.api.live_streams_write`", "operationId": "post_v1_devices_hardwareid_live_stream_stop", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.live_streams_write" ] } ] } }, "/v1/devices/{hardwareId}/playback/calendar": { "get": { "tags": [ "Streaming" ], "summary": "List days with recorded footage for a device", "description": "Returns the days on which the device has recorded footage available for remote playback.\n\n**Required scope:** `thirdparty.api.playback_sessions_write`", "operationId": "get_v1_devices_hardwareid_playback_calendar", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "quality", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackCalendarResponse" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.playback_sessions_write" ] } ] } }, "/v1/devices/{hardwareId}/playback/files": { "get": { "tags": [ "Streaming" ], "summary": "List recorded footage files for a device on a day", "description": "Lists the recorded footage files for a device on a given day and set of channels.\n\n**Required scope:** `thirdparty.api.playback_sessions_write`", "operationId": "get_v1_devices_hardwareid_playback_files", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "day", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "channels", "in": "query", "schema": { "type": "string" } }, { "name": "quality", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackFilesResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.playback_sessions_write" ] } ] } }, "/v1/devices/{hardwareId}/playback": { "post": { "tags": [ "Streaming" ], "summary": "Start a remote-playback HLS session over a time window", "description": "Starts a remote-playback HLS session over a time window and returns per-channel stream URLs. Requires an `Idempotency-Key` header. Streamax devices only; unsupported devices return 422.\n\n**Required scope:** `thirdparty.api.playback_sessions_write`", "operationId": "post_v1_devices_hardwareid_playback", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Client-generated idempotency key. Replaying the same key with the same body returns the original result; reusing it with a different body returns `422 idempotency.conflict`.", "required": true, "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPlaybackCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaybackResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.playback_sessions_write" ] } ] } }, "/v1/devices/{hardwareId}/playback/stop": { "post": { "tags": [ "Streaming" ], "summary": "Stop a device's remote-playback session", "description": "Stops the device's remote-playback session. Returns 204.\n\n**Required scope:** `thirdparty.api.playback_sessions_write`", "operationId": "post_v1_devices_hardwareid_playback_stop", "parameters": [ { "name": "hardwareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.playback_sessions_write" ] } ] } }, "/v1/vehicles": { "get": { "tags": [ "Vehicles" ], "summary": "Search vehicles", "description": "Lists vehicles visible to the caller, optionally filtered by organization or fleet. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.vehicles_read`", "operationId": "get_v1_vehicles", "parameters": [ { "name": "organization_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "fleet_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "maximum": 500, "minimum": 1, "type": "integer", "description": "Maximum number of items to return (1–500). Defaults to 50.", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagedResponseOfVehicleModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.vehicles_read" ] } ] }, "post": { "tags": [ "Vehicles" ], "summary": "Create vehicle", "description": "Creates a vehicle in a fleet within the caller's tenant. Returns the created resource with a Location header.\n\n**Required scope:** `thirdparty.api.vehicles_write`", "operationId": "post_v1_vehicles", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVehicleCommand" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.vehicles_write" ] } ] } }, "/v1/vehicles/{id}": { "get": { "tags": [ "Vehicles" ], "summary": "Get vehicle by id", "description": "Retrieves a single vehicle master record by its identifier.\n\n**Required scope:** `thirdparty.api.vehicles_read`", "operationId": "get_v1_vehicles_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.vehicles_read" ] } ] }, "put": { "tags": [ "Vehicles" ], "summary": "Update vehicle", "description": "Updates an existing vehicle's mutable attributes.\n\n**Required scope:** `thirdparty.api.vehicles_write`", "operationId": "put_v1_vehicles_id_guid", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVehicleCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.vehicles_write" ] } ] } }, "/v1/vehicles/{id}/last-reported": { "get": { "tags": [ "Vehicles" ], "summary": "Get a vehicle's last reported position and status", "description": "Returns the vehicle's most recently reported position and live status from the telemetry store. 404 when the vehicle has no assigned device or no telemetry yet.\n\n**Required scope:** `thirdparty.api.vehicles_read`", "operationId": "get_v1_vehicles_id_guid_last_reported", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LastReportedModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.vehicles_read" ] } ] } }, "/v1/vehicles/{id}/current-journey": { "get": { "tags": [ "Vehicles" ], "summary": "Get a vehicle's in-progress journey summary", "description": "Returns a lightweight summary of the vehicle's in-progress journey. 404 `vehicle.not_found` when the vehicle does not exist or is out of scope; 404 `journey.not_in_progress` when the vehicle exists but has no journey currently in progress.\n\n**Required scope:** `thirdparty.api.vehicles_read`", "operationId": "get_v1_vehicles_id_guid_current_journey", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentJourneyModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.vehicles_read" ] } ] } }, "/v1/video-requests": { "post": { "tags": [ "Video Requests" ], "summary": "Request a video clip from a device", "description": "Queues an on-demand video clip for a device around a centre time (202 Accepted). Requires an `Idempotency-Key` header; reusing a key with a different body returns 422 `idempotency.conflict`.\n\n**Required scope:** `thirdparty.api.video_requests_write`", "operationId": "post_v1_video_requests", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Client-generated idempotency key. Replaying the same key with the same body returns the original result; reusing it with a different body returns `422 idempotency.conflict`.", "required": true, "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoRequestCommand" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoRequestResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.video_requests_write" ] } ] } }, "/v1/video-requests/{id}": { "get": { "tags": [ "Video Requests" ], "summary": "Get a video request", "description": "Returns the status of a video request and, once completed, SAS-signed download URLs for the produced media. When the status is `failed`, `failure_reason` explains why (`cancelled`, `no_footage`, or `device_error`); it is omitted for every other status.\n\n**Required scope:** `thirdparty.api.video_requests_write`", "operationId": "get_v1_video_requests_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoRequestModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.video_requests_write" ] } ] } }, "/v1/events/{event_id}/video-requests": { "post": { "tags": [ "Video Requests" ], "summary": "Request a video clip correlated to an event", "description": "Queues an on-demand video clip whose window is derived from the event (202 Accepted). Requires an `Idempotency-Key` header; reusing a key with a different body returns 422 `idempotency.conflict`.\n\n**Required scope:** `thirdparty.api.video_requests_write`", "operationId": "post_v1_events_event_id_video_requests", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Client-generated idempotency key. Replaying the same key with the same body returns the original result; reusing it with a different body returns `422 idempotency.conflict`.", "required": true, "schema": { "maxLength": 200, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEventVideoRequestCommand" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVideoRequestResult" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.video_requests_write" ] } ] } }, "/v1/organizations/{organizationId}/webhook-config": { "get": { "tags": [ "Webhook Config" ], "summary": "Get webhook configuration", "description": "Retrieve an organization's webhook configuration. Secrets are redacted to a hint. The response carries an ETag for optimistic concurrency.\n\n**Required scope:** `thirdparty.api.webhooks_read`", "operationId": "get_v1_organizations_organizationid_guid_webhook_config", "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.webhooks_read" ] } ] }, "put": { "tags": [ "Webhook Config" ], "summary": "Create or replace webhook configuration", "description": "Create-or-replace the whole webhook configuration. A first configuration must use `is_enabled: false` until its one-time auth key has been captured; enabling it immediately returns 422. Omit If-Match only for first creation; replacing an existing configuration requires its current ETag and a stale value returns 412.\n\n**Required scope:** `thirdparty.api.webhooks_write`", "operationId": "put_v1_organizations_organizationid_guid_webhook_config", "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "description": "Omit only when creating a configuration that does not exist. When replacing an existing configuration, this header is required and must contain the current ETag returned by GET.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceWebhookConfigCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Precondition Failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.webhooks_write" ] } ] }, "patch": { "tags": [ "Webhook Config" ], "summary": "Enable or disable webhook delivery", "description": "Toggles delivery for the organization's webhook configuration. Honours the `If-Match` header; a stale ETag returns 412. Changes can take up to 60 seconds to reach all producer instances.\n\n**Required scope:** `thirdparty.api.webhooks_write`", "operationId": "patch_v1_organizations_organizationid_guid_webhook_config", "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "description": "Required optimistic-concurrency token. Supply the current ETag returned by GET; a missing or stale value returns `412 concurrency.conflict`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchWebhookConfigCommand" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Precondition Failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.webhooks_write" ] } ] }, "delete": { "tags": [ "Webhook Config" ], "summary": "Delete webhook configuration", "description": "Deletes the organization's webhook configuration. Honours the `If-Match` header; a stale ETag returns 412. Delivery suppression can take up to 60 seconds to reach all producer instances.\n\n**Required scope:** `thirdparty.api.webhooks_write`", "operationId": "delete_v1_organizations_organizationid_guid_webhook_config", "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "description": "Required optimistic-concurrency token. Supply the current ETag returned by GET; a missing or stale value returns `412 concurrency.conflict`.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Precondition Failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.webhooks_write" ] } ] } }, "/v1/organizations/{organizationId}/webhook-config/regenerate-auth-key": { "post": { "tags": [ "Webhook Config" ], "summary": "Regenerate the webhook auth key", "description": "Rotate the auth key. The new raw key is returned exactly once and cannot be retrieved later; store it immediately. Producer instances can continue using the previous key for up to 60 seconds while the change propagates. A concurrent configuration update can return 412.\n\n**Required scope:** `thirdparty.api.webhooks_write`", "operationId": "post_v1_organizations_organizationid_guid_webhook_config_regenerate_auth_key", "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAuthKeyModel" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Precondition Failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.webhooks_write" ] } ] } }, "/v1/organizations/{organizationId}/webhook-config/topics/{topicType}": { "put": { "tags": [ "Webhook Config" ], "summary": "Add or replace a webhook topic", "description": "Upsert a single topic by type (events, alarms, media, live_gps, journeys). The current ETag is required in If-Match. Write-time validation rejects unsafe literal URLs; the dispatcher separately enforces DNS and destination-IP safety. A maximum of 25 topics is allowed.\n\n**Required scope:** `thirdparty.api.webhooks_write`", "operationId": "put_v1_organizations_organizationid_guid_webhook_config_topics_topictype", "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "topicType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookTopicType" } }, { "name": "If-Match", "in": "header", "description": "Required optimistic-concurrency token. Supply the current ETag returned by GET; a missing or stale value returns `412 concurrency.conflict`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTopicBodyInput" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigModel" } } } }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Precondition Failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.webhooks_write" ] } ] }, "delete": { "tags": [ "Webhook Config" ], "summary": "Remove a webhook topic", "description": "Remove a single topic by type using the current ETag in If-Match. The last remaining topic cannot be removed (409).\n\n**Required scope:** `thirdparty.api.webhooks_write`", "operationId": "delete_v1_organizations_organizationid_guid_webhook_config_topics_topictype", "parameters": [ { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "topicType", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/WebhookTopicType" } }, { "name": "If-Match", "in": "header", "description": "Required optimistic-concurrency token. Supply the current ETag returned by GET; a missing or stale value returns `412 concurrency.conflict`.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "412": { "description": "Precondition Failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized — the bearer token is missing, malformed or expired.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Forbidden — the token lacks the required scope, or the requested organization is outside the caller's tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Too Many Requests — the per-client rate limit or monthly quota was exceeded. See the `Retry-After` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Internal Server Error — an unexpected error occurred.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "503": { "description": "Service Unavailable — a downstream dependency is temporarily unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "OAuth2": [ "thirdparty.api.webhooks_write" ] } ] } } }, "components": { "schemas": { "AlarmTriggeredWebhookPayload": { "required": [ "id", "hardwareId", "triggerOn", "alarmKey" ], "type": "object", "properties": { "id": { "type": "string" }, "hardwareId": { "type": "string" }, "triggerOn": { "type": "string", "format": "date-time" }, "alarmKey": { "type": "string" }, "headingPoints": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "speedPoints": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookGeoPoint" } }, "source": { "type": "string" }, "vendorAlarmKey": { "type": "string" }, "additionalFields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Vendor-specific extra fields." } }, "description": "`alarm.triggered` — the public shape of the ingress alarm message." }, "AssignDeviceVehicleCommand": { "type": "object", "properties": { "vehicle_id": { "type": "string", "description": "Identifier of the vehicle to assign the device to", "format": "uuid" } } }, "CloudEventEnvelope": { "required": [ "id", "source", "type", "specversion" ], "type": "object", "properties": { "id": { "type": "string", "description": "Producer idempotency key (event id, alarm id, or `hardwareId:utc`)." }, "source": { "type": "string", "description": "Event source context, for example `/brigade/events`.", "format": "uri-reference" }, "type": { "type": "string", "description": "Event type discriminator (see the individual webhooks)." }, "specversion": { "enum": [ "1.0" ], "type": "string", "description": "CloudEvents specification version." }, "time": { "type": "string", "description": "Event time (device wire time).", "format": "date-time" }, "datacontenttype": { "type": "string", "description": "Media type of `data`.", "default": "application/json" }, "subject": { "type": "string", "description": "Subject of the event (device / hardware id)." }, "dataschema": { "type": "string", "description": "URI of the schema that `data` adheres to.", "format": "uri" }, "data": { "type": "object", "description": "The type-specific payload." } }, "description": "CloudEvents 1.0 structured-mode envelope. `data` carries the type-specific payload." }, "CreateDriverCommand": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": [ "null", "string" ] }, "organization_id": { "type": "string", "format": "uuid" }, "fleet_id": { "type": "string", "format": "uuid" } } }, "CreateEventVideoRequestCommand": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Channels to capture (1-based channel numbers)" }, "video_length_seconds": { "type": "integer", "description": "Clip length in seconds", "format": "int32" }, "quality": { "oneOf": [ { "type": "null" }, { "description": "Stream quality (main|sub); defaults to main", "$ref": "#/components/schemas/VideoQuality" } ] }, "with_overlay": { "type": "boolean", "description": "Whether to burn the telemetry overlay into the clip" } } }, "CreateFleetCommand": { "type": "object", "properties": { "name": { "maxLength": 200, "type": "string" }, "organization_id": { "type": "string", "format": "uuid" } } }, "CreateVehicleCommand": { "type": "object", "properties": { "registration_number": { "type": "string" }, "fleet_id": { "type": "string", "format": "uuid" }, "manufacturer": { "maxLength": 50, "type": [ "null", "string" ] }, "model": { "maxLength": 50, "type": [ "null", "string" ] }, "chassis_number": { "type": [ "null", "string" ] }, "type": { "$ref": "#/components/schemas/VehicleType" }, "fuel_type": { "$ref": "#/components/schemas/FuelType" }, "year_of_manufacture": { "type": "integer", "format": "int32" }, "engine_size": { "type": "number", "format": "double" }, "enabled": { "type": "boolean" }, "hex_color": { "type": [ "null", "string" ] }, "emission_factor_grams_co2e_per_km": { "type": "number", "format": "double" } } }, "CreateVideoRequestCommand": { "type": "object", "properties": { "hardware_id": { "type": "string", "description": "Device hardware id" }, "utc": { "type": "string", "description": "UTC centre time of the clip; the window is utc − video_length_seconds/2 .. +/2", "format": "date-time" }, "video_length_seconds": { "type": "integer", "description": "Clip length in seconds", "format": "int32" }, "channels": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Channels to capture (1-based channel numbers)" }, "quality": { "oneOf": [ { "type": "null" }, { "description": "Stream quality (main|sub); defaults to main", "$ref": "#/components/schemas/VideoQuality" } ] }, "with_overlay": { "type": "boolean", "description": "Whether to burn the telemetry overlay into the clip" }, "notifications": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/VideoNotificationModel" }, "description": "Optional notification preferences for when the clip is ready" } } }, "CreateVideoRequestResult": { "required": [ "id", "hardware_id", "is_online" ], "type": "object", "properties": { "id": { "type": "string" }, "hardware_id": { "type": "string" }, "is_online": { "type": "boolean" } } }, "CurrentJourneyModel": { "required": [ "journey_id", "vehicle_id", "hardware_id", "in_progress", "start_utc", "start_point", "length_meters", "time_seconds", "idle_time_seconds", "max_speed_kph" ], "type": "object", "properties": { "journey_id": { "type": "string" }, "vehicle_id": { "type": "string", "format": "uuid" }, "hardware_id": { "type": "string" }, "in_progress": { "type": "boolean" }, "start_utc": { "type": "string", "format": "date-time" }, "start_point": { "$ref": "#/components/schemas/JourneyStartPoint" }, "length_meters": { "type": [ "null", "number" ], "format": "double" }, "time_seconds": { "type": "number", "format": "double" }, "idle_time_seconds": { "type": "number", "format": "double" }, "max_speed_kph": { "type": "integer", "format": "int32" } } }, "DeviceCommandResponse": { "required": [ "id", "command", "status" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "command": { "type": "string" }, "status": { "type": "string" } } }, "DeviceConnectionState": { "enum": [ "unknown", "connected", "disconnected" ], "type": "string" }, "DeviceEventSummaryModel": { "required": [ "event_id", "event_types", "event_categories", "classification", "trigger_utc", "hardware_id", "vehicle_id", "vehicle_registration_number", "driver_id", "fleet_id", "organization_id", "is_accident", "is_important" ], "type": "object", "properties": { "event_id": { "type": "string" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "event_categories": { "type": "array", "items": { "$ref": "#/components/schemas/EventCategory" } }, "classification": { "$ref": "#/components/schemas/EventClassification" }, "trigger_utc": { "type": "string", "format": "date-time" }, "hardware_id": { "type": "string" }, "vehicle_id": { "type": [ "null", "string" ], "format": "uuid" }, "vehicle_registration_number": { "type": [ "null", "string" ] }, "driver_id": { "type": [ "null", "string" ], "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "organization_id": { "type": [ "null", "string" ], "format": "uuid" }, "is_accident": { "type": "boolean" }, "is_important": { "type": "boolean" } } }, "DeviceLastPositionModel": { "required": [ "hardware_id", "vehicle_id", "fleet_id", "utc", "location", "speed_kph", "heading", "address", "speed_limit_kph", "motion_status", "connection_state" ], "type": "object", "properties": { "hardware_id": { "type": "string" }, "vehicle_id": { "type": [ "null", "string" ], "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "utc": { "type": "string", "format": "date-time" }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceLocationModel" } ] }, "speed_kph": { "type": "integer", "format": "int32" }, "heading": { "type": "integer", "format": "int32" }, "address": { "type": [ "null", "string" ] }, "speed_limit_kph": { "type": [ "null", "integer" ], "format": "int32" }, "motion_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MotionStatus" } ] }, "connection_state": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeviceConnectionState" } ] } } }, "DeviceLastReportedModel": { "required": [ "hardware_id", "connection_state", "connection_state_utc", "enabled", "firmware_version", "serial_number", "sim_number", "organization_id", "fleet_id", "vehicle_id", "vehicle_registration_number" ], "type": "object", "properties": { "hardware_id": { "type": "string" }, "connection_state": { "$ref": "#/components/schemas/DeviceConnectionState" }, "connection_state_utc": { "type": [ "null", "string" ], "format": "date-time" }, "enabled": { "type": "boolean" }, "firmware_version": { "type": [ "null", "string" ] }, "serial_number": { "type": [ "null", "string" ] }, "sim_number": { "type": [ "null", "string" ] }, "organization_id": { "type": [ "null", "string" ], "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "vehicle_id": { "type": [ "null", "string" ], "format": "uuid" }, "vehicle_registration_number": { "type": [ "null", "string" ] } } }, "DeviceLocationModel": { "required": [ "lat", "lng" ], "type": "object", "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" } } }, "DeviceMediaModel": { "required": [ "media_id", "file_name", "channel", "media_purpose", "mime_type", "date_captured", "event_id", "download_url" ], "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "file_name": { "type": [ "null", "string" ] }, "channel": { "type": "integer", "format": "int32" }, "media_purpose": { "$ref": "#/components/schemas/MediaPurposeType" }, "mime_type": { "type": [ "null", "string" ] }, "date_captured": { "type": [ "null", "string" ], "format": "date-time" }, "event_id": { "type": [ "null", "string" ] }, "download_url": { "type": [ "null", "string" ] } } }, "DeviceModel": { "required": [ "id", "hardware_id", "serial_number", "sim_number", "iccid", "firmware_version", "organization_id", "fleet_id", "vehicle_id", "enabled", "first_reported", "created_on", "modified_on" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "hardware_id": { "type": "string" }, "serial_number": { "type": [ "null", "string" ] }, "sim_number": { "type": [ "null", "string" ] }, "iccid": { "type": [ "null", "string" ] }, "firmware_version": { "type": [ "null", "string" ] }, "organization_id": { "type": [ "null", "string" ], "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "vehicle_id": { "type": [ "null", "string" ], "format": "uuid" }, "enabled": { "type": "boolean" }, "first_reported": { "type": [ "null", "string" ], "format": "date-time" }, "created_on": { "type": "string", "format": "date-time" }, "modified_on": { "type": [ "null", "string" ], "format": "date-time" } } }, "DevicePowerState": { "enum": [ "unknown", "awake", "dormant" ], "type": "string" }, "DriverModel": { "required": [ "id", "name", "first_name", "last_name", "phone_number", "organization_id", "fleet_id", "created_on", "modified_on" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": [ "null", "string" ] }, "organization_id": { "type": "string", "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "created_on": { "type": "string", "format": "date-time" }, "modified_on": { "type": [ "null", "string" ], "format": "date-time" } } }, "EventAddress": { "required": [ "label", "country", "state", "county", "city", "district", "street", "house_number", "postal_code" ], "type": "object", "properties": { "label": { "type": [ "null", "string" ] }, "country": { "type": [ "null", "string" ] }, "state": { "type": [ "null", "string" ] }, "county": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "district": { "type": [ "null", "string" ] }, "street": { "type": [ "null", "string" ] }, "house_number": { "type": [ "null", "string" ] }, "postal_code": { "type": [ "null", "string" ] } } }, "EventCategory": { "enum": [ "none", "driver_behaviour", "safety_and_security", "driver_state_monitoring", "vehicle_state_monitoring", "advanced_driver_assistance_systems", "diagnostics" ], "type": "string" }, "EventClassification": { "enum": [ "unclassified", "requested", "green", "amber", "red" ], "type": "string" }, "EventFilterMode": { "enum": [ "all", "include", "exclude" ], "type": "string" }, "EventGenericWebhookPayload": { "required": [ "eventId", "hardwareId", "triggerUtc" ], "type": "object", "properties": { "eventId": { "type": "string" }, "hardwareId": { "type": "string" }, "triggerUtc": { "type": "string", "format": "date-time" }, "receivedUtc": { "type": "string", "format": "date-time" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "eventCategories": { "type": "array", "items": { "type": "string" } }, "classification": { "type": "string" }, "status": { "type": "string" }, "isAccident": { "type": "boolean" }, "isImportant": { "type": "boolean" }, "maxSpeedKph": { "type": "integer", "format": "int32" }, "speedLimitKph": { "type": "integer", "format": "int32" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookGeoPoint" } }, "speedPoints": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "headingPoints": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "gSensorFrames": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookGSensorFrame" } }, "address": { "$ref": "#/components/schemas/WebhookAddress" }, "mediaStatus": { "type": "string" }, "vehicleId": { "type": "string", "format": "uuid" }, "vehicleRegistrationNumber": { "type": "string" }, "driverId": { "type": "string", "format": "uuid" }, "fleetId": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" } }, "description": "`event.generic` — a trimmed public projection of a device event." }, "EventGeometryKind": { "enum": [ "point", "segment" ], "type": "string" }, "EventGSensorFrame": { "required": [ "x_axis", "y_axis", "z_axis", "utc_timestamp", "sequence_number" ], "type": "object", "properties": { "x_axis": { "type": "number", "format": "double" }, "y_axis": { "type": "number", "format": "double" }, "z_axis": { "type": "number", "format": "double" }, "utc_timestamp": { "type": "string", "format": "date-time" }, "sequence_number": { "type": "integer", "format": "int64" } } }, "EventListItemModel": { "required": [ "event_id", "event_types", "event_categories", "classification", "trigger_utc", "hardware_id", "vehicle_id", "vehicle_registration_number", "driver_id", "fleet_id", "organization_id", "is_accident", "is_important" ], "type": "object", "properties": { "event_id": { "type": "string" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "event_categories": { "type": "array", "items": { "$ref": "#/components/schemas/EventCategory" } }, "classification": { "$ref": "#/components/schemas/EventClassification" }, "trigger_utc": { "type": "string", "format": "date-time" }, "hardware_id": { "type": "string" }, "vehicle_id": { "type": [ "null", "string" ], "format": "uuid" }, "vehicle_registration_number": { "type": [ "null", "string" ] }, "driver_id": { "type": [ "null", "string" ], "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "organization_id": { "type": [ "null", "string" ], "format": "uuid" }, "is_accident": { "type": "boolean" }, "is_important": { "type": "boolean" } } }, "EventLocation": { "required": [ "lat", "lng" ], "type": "object", "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" } } }, "EventMediaModel": { "required": [ "media_id", "file_name", "channel", "media_purpose", "mime_type", "date_captured", "event_id", "download_url" ], "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "file_name": { "type": [ "null", "string" ] }, "channel": { "type": "integer", "format": "int32" }, "media_purpose": { "$ref": "#/components/schemas/MediaPurposeType" }, "mime_type": { "type": [ "null", "string" ] }, "date_captured": { "type": [ "null", "string" ], "format": "date-time" }, "event_id": { "type": [ "null", "string" ] }, "download_url": { "type": [ "null", "string" ] } } }, "EventModel": { "required": [ "event_id", "hardware_id", "trigger_utc", "received_utc", "event_types", "event_categories", "classification", "status", "is_accident", "is_important", "max_speed_kph", "speed_limit_kph", "locations", "speed_points", "heading_points", "g_sensor_frames", "address", "media_status", "vehicle_id", "vehicle_registration_number", "driver_id", "fleet_id", "organization_id", "g_sensor_data_url" ], "type": "object", "properties": { "event_id": { "type": "string" }, "hardware_id": { "type": "string" }, "trigger_utc": { "type": "string", "format": "date-time" }, "received_utc": { "type": "string", "format": "date-time" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "event_categories": { "type": "array", "items": { "$ref": "#/components/schemas/EventCategory" } }, "classification": { "$ref": "#/components/schemas/EventClassification" }, "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EventStatus" } ] }, "is_accident": { "type": "boolean" }, "is_important": { "type": "boolean" }, "max_speed_kph": { "type": [ "null", "integer" ], "format": "int32" }, "speed_limit_kph": { "type": "integer", "format": "int32" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/EventLocation" } }, "speed_points": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "heading_points": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "g_sensor_frames": { "type": "array", "items": { "$ref": "#/components/schemas/EventGSensorFrame" } }, "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EventAddress" } ] }, "media_status": { "$ref": "#/components/schemas/MediaStatus" }, "vehicle_id": { "type": [ "null", "string" ], "format": "uuid" }, "vehicle_registration_number": { "type": [ "null", "string" ] }, "driver_id": { "type": [ "null", "string" ], "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "organization_id": { "type": [ "null", "string" ], "format": "uuid" }, "g_sensor_data_url": { "type": [ "null", "string" ] } } }, "EventStatus": { "enum": [ "incident", "dismissed", "footage_requested", "requires_intervention", "not_processed" ], "type": [ "null", "string" ] }, "EventType": { "enum": [ "unknown", "speed", "brake", "accelerate", "shock", "turn", "button", "fatigue", "smoking", "distraction", "no_driver", "mobile_phone_warning", "vehicle_detected", "seatbelt", "door", "left_hand_indicator", "right_hand_indicator", "vehicle_reversing", "ignition_on", "ignition_off", "lane_departure", "forward_collision_warning", "following_distance_warning", "human_detection", "bridge_detection", "bridge_passable", "bridge_over_height", "diagnostics", "system", "gps_fault", "video_loss", "storage_abnormal", "camera_covered", "video_request", "snapshot_request" ], "type": "string" }, "FleetModel": { "required": [ "id", "name", "organization_id", "created_on", "modified_on" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "created_on": { "type": "string", "format": "date-time" }, "modified_on": { "type": [ "null", "string" ], "format": "date-time" } } }, "FuelType": { "enum": [ "diesel", "electric", "hybrid", "lpg", "petrol", "other" ], "type": "string" }, "GeometryEncoding": { "enum": [ "google6" ], "type": [ "null", "string" ] }, "GeoPoint": { "required": [ "lat", "lng" ], "type": "object", "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" } } }, "GpsState": { "enum": [ "unknown", "valid", "invalid" ], "type": "string" }, "JourneyAddress": { "type": "object", "properties": { "label": { "type": [ "null", "string" ] }, "country": { "type": [ "null", "string" ] }, "state": { "type": [ "null", "string" ] }, "county": { "type": [ "null", "string" ] }, "city": { "type": [ "null", "string" ] }, "district": { "type": [ "null", "string" ] }, "street": { "type": [ "null", "string" ] }, "house_number": { "type": [ "null", "string" ] }, "postal_code": { "type": [ "null", "string" ] } } }, "JourneyClosedWebhookPayload": { "required": [ "journeyId", "hardwareId", "startUtc", "endUtc" ], "type": "object", "properties": { "journeyId": { "type": "string" }, "hardwareId": { "type": "string" }, "organizationId": { "type": "string", "format": "uuid" }, "startUtc": { "type": "string", "format": "date-time" }, "endUtc": { "type": "string", "format": "date-time" }, "startLatitude": { "type": "number", "format": "double" }, "startLongitude": { "type": "number", "format": "double" }, "endLatitude": { "type": "number", "format": "double" }, "endLongitude": { "type": "number", "format": "double" }, "distanceMeters": { "type": "number", "format": "double" }, "durationSeconds": { "type": "number", "format": "double" } }, "description": "`journey.closed` — a lean closed-journey summary." }, "JourneyDeviceEventRef": { "required": [ "hardware_id", "event_id" ], "type": "object", "properties": { "hardware_id": { "type": "string" }, "event_id": { "type": "string", "format": "uuid" } } }, "JourneyDeviceRef": { "required": [ "hardware_id" ], "type": "object", "properties": { "hardware_id": { "type": "string" }, "device_model_id": { "type": [ "null", "string" ], "format": "uuid" }, "device_protocol_id": { "type": [ "null", "string" ], "format": "uuid" } } }, "JourneyEndpointInfo": { "required": [ "utc" ], "type": "object", "properties": { "utc": { "type": "string", "format": "date-time" }, "place": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyPlace" } ] } } }, "JourneyEntityReference": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "null", "string" ] } } }, "JourneyEventGeometry": { "required": [ "kind" ], "type": "object", "properties": { "kind": { "$ref": "#/components/schemas/EventGeometryKind" }, "dist_along_start": { "type": [ "null", "number" ], "format": "double" }, "dist_along_end": { "type": [ "null", "number" ], "format": "double" }, "polyline": { "type": [ "null", "string" ] }, "time_window_start": { "type": [ "null", "string" ], "format": "date-time" }, "time_window_end": { "type": [ "null", "string" ], "format": "date-time" }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyGeoPoint" } } } }, "JourneyEventMarker": { "required": [ "event_id", "hardware_id", "lat", "lng", "utc", "geometry" ], "type": "object", "properties": { "event_id": { "type": "string", "format": "uuid" }, "hardware_id": { "type": "string" }, "device_event_ref": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyDeviceEventRef" } ] }, "types": { "type": "array", "items": { "type": "string" } }, "classification": { "type": [ "null", "string" ] }, "flags": { "type": "array", "items": { "type": "string" } }, "event_categories": { "type": "array", "items": { "type": "string" } }, "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "utc": { "type": "string", "format": "date-time" }, "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyAddress" } ] }, "speed_kph": { "type": [ "null", "integer" ], "format": "int32" }, "speed_limit_kph": { "type": [ "null", "integer" ], "format": "int32" }, "max_speed_kph": { "type": [ "null", "integer" ], "format": "int32" }, "max_speed_limit_kph": { "type": [ "null", "integer" ], "format": "int32" }, "media_status": { "type": [ "null", "string" ] }, "geometry": { "$ref": "#/components/schemas/JourneyEventGeometry" } } }, "JourneyGeofenceReference": { "required": [ "name" ], "type": "object", "properties": { "id": { "type": [ "null", "string" ], "format": "uuid" }, "name": { "type": "string" } } }, "JourneyGeometry": { "type": "object", "properties": { "trackpoints": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyGeoPoint" } }, "speed_events": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyEventMarker" } }, "gps_loss": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyGpsLossRange" } }, "idle": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyIdleStop" } } } }, "JourneyGeoPoint": { "required": [ "lat", "lng", "utc" ], "type": "object", "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "raw_lat": { "type": [ "null", "number" ], "format": "double" }, "raw_lng": { "type": [ "null", "number" ], "format": "double" }, "utc": { "type": "string", "format": "date-time" }, "speed_kph": { "type": [ "null", "integer" ], "format": "int32" }, "speed_limit_kph": { "type": [ "null", "integer" ], "format": "int32" }, "dist_along": { "type": [ "null", "number" ], "format": "double" }, "route_distance_meters": { "type": [ "null", "number" ], "format": "double" }, "route_index": { "type": [ "null", "integer" ], "format": "int32" } } }, "JourneyGpsLossRange": { "type": "object", "properties": { "from": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyGeoPoint" } ] }, "to": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyGeoPoint" } ] } } }, "JourneyIdleStop": { "required": [ "start", "end", "lat", "lng", "duration_seconds" ], "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "duration_seconds": { "type": "integer", "format": "int32" } } }, "JourneyMetrics": { "type": "object", "properties": { "distance_meters": { "type": [ "null", "integer" ], "format": "int32" }, "duration_seconds": { "type": [ "null", "integer" ], "format": "int32" }, "moving_seconds": { "type": [ "null", "integer" ], "format": "int32" }, "idle_seconds": { "type": [ "null", "integer" ], "format": "int32" }, "engine_seconds": { "type": [ "null", "integer" ], "format": "int32" }, "start_odometer_meters": { "type": [ "null", "integer" ], "format": "int32" }, "end_odometer_meters": { "type": [ "null", "integer" ], "format": "int32" } } }, "JourneyModel": { "required": [ "id", "status", "map_match_state", "device", "start", "metrics", "gps_valid", "no_gps", "raw_available" ], "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/JourneyStatus" }, "map_match_state": { "$ref": "#/components/schemas/MapMatchState" }, "device": { "$ref": "#/components/schemas/JourneyDeviceRef" }, "driver": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyEntityReference" } ] }, "purpose": { "$ref": "#/components/schemas/JourneyPurpose" }, "start": { "$ref": "#/components/schemas/JourneyEndpointInfo" }, "end": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyEndpointInfo" } ] }, "metrics": { "$ref": "#/components/schemas/JourneyMetrics" }, "gps_valid": { "type": "boolean" }, "no_gps": { "type": "boolean" }, "raw_available": { "type": "boolean" }, "raw_available_until": { "type": [ "null", "string" ], "format": "date-time" }, "version": { "type": [ "null", "integer" ], "format": "int32" }, "point_count": { "type": [ "null", "integer" ], "format": "int32" }, "bbox": { "type": [ "null", "array" ], "items": { "type": "number", "format": "double" } }, "route_polyline": { "type": [ "null", "string" ] }, "geometry_encoding": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeometryEncoding" } ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyEventMarker" } }, "geometry": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyGeometry" } ] }, "reprocess_info": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyReprocessInfo" } ] } } }, "JourneyPlace": { "required": [ "lat", "lng" ], "type": "object", "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyAddress" } ] }, "geofence": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyGeofenceReference" } ] }, "poi": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JourneyEntityReference" } ] } } }, "JourneyPurpose": { "enum": [ "business", "private" ], "type": "string" }, "JourneyReprocessInfo": { "required": [ "last_reprocessed" ], "type": "object", "properties": { "last_reprocessed": { "type": "string", "format": "date-time" }, "created": { "type": [ "null", "integer" ], "format": "int32" }, "snapped": { "type": [ "null", "integer" ], "format": "int32" }, "raw": { "type": [ "null", "integer" ], "format": "int32" }, "deleted": { "type": [ "null", "integer" ], "format": "int32" } } }, "JourneyStartPoint": { "required": [ "lat", "lng", "utc" ], "type": "object", "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" }, "utc": { "type": "string", "format": "date-time" } } }, "JourneyStatus": { "enum": [ "live", "unprocessed", "processed" ], "type": "string" }, "LastReportedModel": { "required": [ "vehicle_id", "hardware_id", "utc", "location", "speed_kph", "heading", "motion_status", "connection_state", "gps_state", "power_state" ], "type": "object", "properties": { "vehicle_id": { "type": "string", "format": "uuid" }, "hardware_id": { "type": "string" }, "utc": { "type": "string", "format": "date-time" }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VehicleGeoPoint" } ] }, "speed_kph": { "type": "integer", "format": "int32" }, "heading": { "type": "integer", "format": "int32" }, "motion_status": { "$ref": "#/components/schemas/MotionStatus" }, "connection_state": { "$ref": "#/components/schemas/DeviceConnectionState" }, "gps_state": { "$ref": "#/components/schemas/GpsState" }, "power_state": { "$ref": "#/components/schemas/DevicePowerState" } } }, "LiveGpsWebhookPayload": { "required": [ "hardwareId", "latitude", "longitude", "utc" ], "type": "object", "properties": { "hardwareId": { "type": "string", "description": "Device hardware id." }, "organizationId": { "type": "string", "format": "uuid" }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "heading": { "type": "number", "description": "Heading in degrees.", "format": "double" }, "speed": { "type": "number", "description": "Speed in km/h.", "format": "double" }, "utc": { "type": "string", "format": "date-time" }, "invalidGps": { "type": "boolean", "description": "True when the fix is not GPS-valid." } }, "description": "`live.gps` — a single live GPS fix." }, "LivePositionModel": { "required": [ "hardware_id", "vehicle_id", "fleet_id", "utc", "location", "speed_kph", "heading", "address", "speed_limit_kph", "motion_status", "connection_state" ], "type": "object", "properties": { "hardware_id": { "type": "string" }, "vehicle_id": { "type": [ "null", "string" ], "format": "uuid" }, "fleet_id": { "type": [ "null", "string" ], "format": "uuid" }, "utc": { "type": "string", "format": "date-time" }, "location": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoPoint" } ] }, "speed_kph": { "type": "integer", "format": "int32" }, "heading": { "type": "integer", "format": "int32" }, "address": { "type": [ "null", "string" ] }, "speed_limit_kph": { "type": [ "null", "integer" ], "format": "int32" }, "motion_status": { "$ref": "#/components/schemas/MotionStatus" }, "connection_state": { "$ref": "#/components/schemas/DeviceConnectionState" } } }, "LiveStreamResponse": { "required": [ "streams" ], "type": "object", "properties": { "streams": { "type": "array", "items": { "$ref": "#/components/schemas/StreamModel" } } } }, "MapMatchState": { "enum": [ "snapped", "raw" ], "type": "string" }, "MediaPurposeType": { "enum": [ "unspecified", "video", "snapshot", "thumbnail", "gif", "video_with_audio" ], "type": "string" }, "MediaReadyWebhookPayload": { "required": [ "mediaId", "hardwareId" ], "type": "object", "properties": { "mediaId": { "type": "string", "format": "uuid" }, "fileName": { "type": "string" }, "mimeType": { "type": "string" }, "fileExtension": { "type": "string" }, "channel": { "type": "integer", "format": "int32" }, "mediaPurpose": { "type": "string" }, "dateCaptured": { "type": "string", "format": "date-time" }, "hardwareId": { "type": "string" }, "eventId": { "type": "string" }, "deviceCommandId": { "type": "string" }, "organizationId": { "type": "string", "format": "uuid" }, "fleetId": { "type": "string", "format": "uuid" }, "vehicleId": { "type": "string", "format": "uuid" }, "downloadUrl": { "type": "string", "description": "Time-limited SAS-signed download URL.", "format": "uri" } }, "description": "`media.ready` — a trimmed public projection of ready media, with a SAS-signed `downloadUrl`." }, "MediaStatus": { "enum": [ "none", "pending", "no_footage", "available" ], "type": "string" }, "MeResponse": { "required": [ "client_id", "org_id", "scopes" ], "type": "object", "properties": { "client_id": { "type": [ "null", "string" ] }, "org_id": { "type": [ "null", "string" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "MotionStatus": { "enum": [ "unknown", "moving", "stopped", "parked" ], "type": "string" }, "OrganizationModel": { "required": [ "id", "name", "time_zone", "support_email", "support_phone_number", "parent_id" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "time_zone": { "type": [ "null", "string" ] }, "support_email": { "type": [ "null", "string" ] }, "support_phone_number": { "type": [ "null", "string" ] }, "parent_id": { "type": [ "null", "string" ], "format": "uuid" } } }, "PagedResponseOfDeviceEventSummaryModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceEventSummaryModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfDeviceMediaModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceMediaModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfDeviceModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfDriverModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DriverModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfEventListItemModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventListItemModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfEventMediaModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventMediaModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfFleetModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FleetModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfJourneyModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JourneyModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfLivePositionModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LivePositionModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfOrganizationModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PagedResponseOfVehicleModel": { "required": [ "data", "next_cursor", "has_more" ], "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleModel" } }, "next_cursor": { "type": [ "null", "string" ] }, "has_more": { "type": "boolean" } } }, "PatchWebhookConfigCommand": { "type": "object", "properties": { "is_enabled": { "type": "boolean" } } }, "PlaybackCalendarResponse": { "required": [ "available_days" ], "type": "object", "properties": { "available_days": { "type": "array", "items": { "type": "string" } } } }, "PlaybackFileModel": { "required": [ "channel", "start", "end", "size_bytes" ], "type": "object", "properties": { "channel": { "type": "integer", "format": "int32" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "size_bytes": { "type": [ "null", "integer" ], "format": "int64" } } }, "PlaybackFilesResponse": { "required": [ "files" ], "type": "object", "properties": { "files": { "type": "array", "items": { "$ref": "#/components/schemas/PlaybackFileModel" } } } }, "PlaybackResponse": { "required": [ "streams" ], "type": "object", "properties": { "streams": { "type": "array", "items": { "$ref": "#/components/schemas/StreamModel" } } } }, "ProblemDetails": { "required": [ "type", "title", "status", "code" ], "type": "object", "properties": { "type": { "type": "string", "description": "A URI identifying the problem type.", "format": "uri" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type." }, "status": { "type": "integer", "description": "The HTTP status code.", "format": "int32" }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "description": "The request path that produced the error." }, "code": { "type": "string", "description": "Stable, machine-readable error code (for example `device.capability_missing`)." }, "trace_id": { "type": "string", "description": "Correlation/trace identifier for support." }, "timestamp": { "type": "string", "description": "UTC time the error was produced.", "format": "date-time" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field-level validation errors, keyed by field name (validation failures only)." } }, "description": "RFC 7807 problem detail. Every error carries a stable, machine-readable `code`; validation failures additionally include a per-field `errors` map." }, "ReplaceWebhookConfigCommand": { "type": "object", "properties": { "is_enabled": { "type": "boolean" }, "topics": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTopicInput" } } } }, "StartLiveStreamCommand": { "type": "object", "properties": { "channels": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Camera channels to stream (1-32)" }, "quality": { "description": "Stream quality: main or sub", "$ref": "#/components/schemas/StreamQuality" } } }, "StartPlaybackCommand": { "type": "object", "properties": { "utc_from": { "type": "string", "description": "Window start (UTC)", "format": "date-time" }, "utc_to": { "type": "string", "description": "Window end (UTC)", "format": "date-time" }, "channels": { "type": "array", "items": { "type": "integer", "format": "int32" }, "description": "Camera channels to play back (1-32)" }, "quality": { "description": "Stream quality: main or sub", "$ref": "#/components/schemas/StreamQuality" } } }, "StreamModel": { "required": [ "channel", "url", "has_audio" ], "type": "object", "properties": { "channel": { "type": "integer", "format": "int32" }, "url": { "type": "string" }, "has_audio": { "type": "boolean" } } }, "StreamQuality": { "enum": [ "main", "sub" ], "type": "string" }, "UpdateDriverCommand": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone_number": { "type": [ "null", "string" ] } } }, "UpdateFleetCommand": { "type": "object", "properties": { "name": { "maxLength": 200, "type": "string" } } }, "UpdateVehicleCommand": { "type": "object", "properties": { "registration_number": { "type": "string" }, "manufacturer": { "maxLength": 50, "type": [ "null", "string" ] }, "model": { "maxLength": 50, "type": [ "null", "string" ] }, "chassis_number": { "type": [ "null", "string" ] }, "type": { "$ref": "#/components/schemas/VehicleType" }, "fuel_type": { "$ref": "#/components/schemas/FuelType" }, "year_of_manufacture": { "type": "integer", "format": "int32" }, "engine_size": { "type": "number", "format": "double" }, "enabled": { "type": "boolean" }, "hex_color": { "type": [ "null", "string" ] }, "emission_factor_grams_co2e_per_km": { "type": "number", "format": "double" } } }, "VehicleGeoPoint": { "required": [ "lat", "lng" ], "type": "object", "properties": { "lat": { "type": "number", "format": "double" }, "lng": { "type": "number", "format": "double" } } }, "VehicleModel": { "required": [ "id", "registration_number", "manufacturer", "model", "chassis_number", "type", "fuel_type", "fleet_id", "driver_id", "enabled", "year_of_manufacture", "created_on", "modified_on" ], "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "registration_number": { "type": "string" }, "manufacturer": { "type": [ "null", "string" ] }, "model": { "type": [ "null", "string" ] }, "chassis_number": { "type": [ "null", "string" ] }, "type": { "$ref": "#/components/schemas/VehicleType" }, "fuel_type": { "$ref": "#/components/schemas/FuelType" }, "fleet_id": { "type": "string", "format": "uuid" }, "driver_id": { "type": [ "null", "string" ], "format": "uuid" }, "enabled": { "type": "boolean" }, "year_of_manufacture": { "type": "integer", "format": "int32" }, "created_on": { "type": "string", "format": "date-time" }, "modified_on": { "type": [ "null", "string" ], "format": "date-time" } } }, "VehicleType": { "enum": [ "unknown", "car", "van", "tractor_trailer", "small_rigid_truck" ], "type": "string" }, "VideoNotificationChannel": { "enum": [ "email", "sms", "whatsapp" ], "type": "string" }, "VideoNotificationModel": { "type": "object", "properties": { "channel": { "$ref": "#/components/schemas/VideoNotificationChannel" }, "target": { "type": "string" } } }, "VideoQuality": { "enum": [ "main", "sub" ], "type": [ "null", "string" ] }, "VideoRequestFailureReason": { "enum": [ "cancelled", "no_footage", "device_error" ], "type": [ "null", "string" ] }, "VideoRequestMediaModel": { "required": [ "media_id", "channel", "download_url" ], "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "channel": { "type": "integer", "format": "int32" }, "download_url": { "type": [ "null", "string" ] } } }, "VideoRequestModel": { "required": [ "id", "status", "failure_reason", "hardware_id", "media" ], "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/VideoRequestStatus" }, "failure_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VideoRequestFailureReason" } ] }, "hardware_id": { "type": "string" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/VideoRequestMediaModel" } } } }, "VideoRequestStatus": { "enum": [ "queued", "in_progress", "completed", "failed" ], "type": "string" }, "WebhookAddress": { "type": "object", "properties": { "label": { "type": "string" }, "country": { "type": "string" }, "state": { "type": "string" }, "county": { "type": "string" }, "city": { "type": "string" }, "district": { "type": "string" }, "street": { "type": "string" }, "houseNumber": { "type": "string" }, "postalCode": { "type": "string" } }, "description": "Reverse-geocoded address of the trigger location." }, "WebhookAuthKeyModel": { "required": [ "auth_key", "auth_key_hint" ], "type": "object", "properties": { "auth_key": { "type": "string" }, "auth_key_hint": { "type": "string" } } }, "WebhookConfigModel": { "required": [ "organization_id", "is_enabled", "auth_key_hint", "source_organization_id", "is_inherited", "topics" ], "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid" }, "is_enabled": { "type": "boolean" }, "auth_key_hint": { "type": [ "null", "string" ] }, "source_organization_id": { "type": "string", "format": "uuid" }, "is_inherited": { "type": "boolean" }, "topics": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTopicModel" } } } }, "WebhookDeliveryInput": { "type": "object", "properties": { "url": { "type": "string", "description": "Webhook callback URL (HTTPS required; blocked literal hosts/IPs are rejected at write time, and DNS/IP safety is enforced at delivery time)" } } }, "WebhookDeliveryModel": { "required": [ "delivery_type", "url" ], "type": "object", "properties": { "delivery_type": { "type": "string" }, "url": { "type": "string" } } }, "WebhookGeoPoint": { "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "type": "number", "description": "Latitude in decimal degrees.", "format": "double" }, "longitude": { "type": "number", "description": "Longitude in decimal degrees.", "format": "double" } }, "description": "A geographic point (WGS-84)." }, "WebhookGSensorFrame": { "type": "object", "properties": { "xAxis": { "type": "number", "format": "double" }, "yAxis": { "type": "number", "format": "double" }, "zAxis": { "type": "number", "format": "double" }, "utcTimestamp": { "type": "string", "format": "date-time" }, "sequenceNumber": { "type": "integer", "format": "int32" } }, "description": "A single g-sensor sample frame." }, "WebhookTopicBodyInput": { "type": "object", "properties": { "is_enabled": { "type": "boolean", "description": "Whether the topic is enabled" }, "delivery": { "description": "Delivery configuration (HttpCallback only)", "$ref": "#/components/schemas/WebhookDeliveryInput" }, "options": { "oneOf": [ { "type": "null" }, { "description": "Topic-specific options (required for the events topic, must be null otherwise)", "$ref": "#/components/schemas/WebhookTopicOptionsInput" } ] } } }, "WebhookTopicInput": { "type": "object", "properties": { "type": { "description": "Topic type (events, alarms, media, live_gps, journeys)", "$ref": "#/components/schemas/WebhookTopicType" }, "is_enabled": { "type": "boolean", "description": "Whether the topic is enabled" }, "delivery": { "description": "Delivery configuration (HttpCallback only)", "$ref": "#/components/schemas/WebhookDeliveryInput" }, "options": { "oneOf": [ { "type": "null" }, { "description": "Topic-specific options (required for the events topic, must be null otherwise)", "$ref": "#/components/schemas/WebhookTopicOptionsInput" } ] } } }, "WebhookTopicModel": { "required": [ "type", "is_enabled", "delivery", "options" ], "type": "object", "properties": { "type": { "$ref": "#/components/schemas/WebhookTopicType" }, "is_enabled": { "type": "boolean" }, "delivery": { "$ref": "#/components/schemas/WebhookDeliveryModel" }, "options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WebhookTopicOptionsModel" } ] } } }, "WebhookTopicOptionsInput": { "type": "object", "properties": { "event_filter_mode": { "description": "Event filter mode (all, include, exclude)", "$ref": "#/components/schemas/EventFilterMode" }, "event_types": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/EventType" }, "description": "Event types to include or exclude" }, "event_categories": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/EventCategory" }, "description": "Event categories to include or exclude" } } }, "WebhookTopicOptionsModel": { "required": [ "event_filter_mode", "event_types", "event_categories" ], "type": "object", "properties": { "event_filter_mode": { "$ref": "#/components/schemas/EventFilterMode" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "event_categories": { "type": "array", "items": { "$ref": "#/components/schemas/EventCategory" } } } }, "WebhookTopicType": { "enum": [ "journeys", "alarms", "events", "media", "live_gps" ], "type": "string" } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "OAuth2 client-credentials. Request a token from the identity provider's token endpoint with the scopes your integration needs, then send it as `Authorization: Bearer `.", "flows": { "clientCredentials": { "tokenUrl": "https://auth.eu.haloniq.com/connect/token", "scopes": { "thirdparty.api.device_commands_reboot": "device commands reboot", "thirdparty.api.device_commands_wake_up": "device commands wake up", "thirdparty.api.devices_read": "devices read", "thirdparty.api.devices_write": "devices write", "thirdparty.api.drivers_read": "drivers read", "thirdparty.api.drivers_write": "drivers write", "thirdparty.api.events_read": "events read", "thirdparty.api.fleets_read": "fleets read", "thirdparty.api.fleets_write": "fleets write", "thirdparty.api.journeys_read": "journeys read", "thirdparty.api.live_positions_read": "live positions read", "thirdparty.api.live_streams_write": "live streams write", "thirdparty.api.organizations_read": "organizations read", "thirdparty.api.playback_sessions_write": "playback sessions write", "thirdparty.api.vehicles_read": "vehicles read", "thirdparty.api.vehicles_write": "vehicles write", "thirdparty.api.video_requests_write": "video requests write", "thirdparty.api.webhooks_read": "webhooks read", "thirdparty.api.webhooks_write": "webhooks write" } } } } } }, "security": [ { "OAuth2": [ ] } ], "tags": [ { "name": "Fleets", "description": "Fleet master data — create, read, update and list fleets." }, { "name": "Drivers", "description": "Driver master data — create, read, update and list drivers." }, { "name": "Organizations", "description": "Read the organizations visible to the caller (own tenant and its descendants)." }, { "name": "Vehicles", "description": "Vehicle master data plus last-reported position and in-progress journey summary." }, { "name": "Devices", "description": "Device master data plus telemetry sub-resources: events, media, last position, assignment and commands." }, { "name": "Events", "description": "Search and read telematics events and their media." }, { "name": "Journeys", "description": "Search and read completed and in-progress journeys." }, { "name": "Live Positions", "description": "Read the latest live position of vehicles and devices." }, { "name": "Video Requests", "description": "Request on-demand video clips from a device or an event and poll their status." }, { "name": "Streaming", "description": "Live HLS streaming and remote playback sessions (Streamax devices)." }, { "name": "Webhook Config", "description": "Manage an organization's outbound webhook configuration and topics." }, { "name": "Meta", "description": "Token introspection and service metadata." }, { "name": "Webhooks", "description": "Outbound CloudEvents 1.0 messages the platform POSTs to your subscriber endpoints." } ], "x-error-codes": [ { "code": "auth.org_forbidden", "description": "The requested organization is outside the caller's tenant, or the request could not be scoped to an organization." }, { "code": "auth.scope_missing", "description": "The token does not carry the scope required by the endpoint." }, { "code": "auth.token_invalid", "description": "The bearer token is missing, malformed, expired or has an invalid audience." }, { "code": "concurrency.conflict", "description": "The `If-Match` ETag is stale; the resource was modified by another writer." }, { "code": "device.capability_missing", "description": "The device does not support the requested command (for example reboot on a non-Streamax device)." }, { "code": "device.not_found", "description": "No device with the given hardware id is visible to the caller." }, { "code": "device.unavailable", "description": "The device is currently offline or otherwise unreachable." }, { "code": "driver.not_found", "description": "No driver with the given id is visible to the caller." }, { "code": "event.not_found", "description": "No event with the given id is visible to the caller." }, { "code": "fleet.not_found", "description": "No fleet with the given id is visible to the caller." }, { "code": "idempotency.conflict", "description": "The `Idempotency-Key` was reused with a different request body." }, { "code": "journey.not_found", "description": "No journey with the given id is visible to the caller." }, { "code": "journey.not_in_progress", "description": "The vehicle exists but has no journey currently in progress." }, { "code": "media.not_found", "description": "No media with the given id is visible to the caller." }, { "code": "organization.not_found", "description": "No organization with the given id is visible to the caller." }, { "code": "pagination.invalid_cursor", "description": "The supplied pagination cursor is malformed or no longer valid." }, { "code": "quota.exceeded", "description": "The monthly request quota was exceeded." }, { "code": "rate_limit.exceeded", "description": "The per-client rate limit was exceeded; see the `Retry-After` header." }, { "code": "server.unavailable", "description": "A downstream dependency is temporarily unavailable." }, { "code": "validation.failed", "description": "The request body or parameters failed validation; see the per-field `errors` map." }, { "code": "vehicle.not_found", "description": "No vehicle with the given id is visible to the caller." }, { "code": "webhook.config_not_found", "description": "No webhook configuration exists for the organization." }, { "code": "webhook.initial_activation_forbidden", "description": "A new webhook configuration must remain disabled until its one-time authentication key has been captured." }, { "code": "webhook.last_topic_required", "description": "The last remaining webhook topic cannot be removed." }, { "code": "webhook.ssrf_blocked", "description": "The webhook delivery URL was rejected by SSRF validation." }, { "code": "webhook.topic_not_found", "description": "The requested webhook topic does not exist." } ], "webhooks": { "live.gps": { "description": "Live GPS fix", "post": { "tags": [ "Webhooks" ], "summary": "Live GPS fix", "description": "Fired for each live GPS fix received from a device (topic `live_gps`). Payloads are lean; use the REST live-positions endpoints for enriched data.", "operationId": "webhook_live_gps", "parameters": [ { "name": "X-Webhook-Key", "in": "header", "description": "The organization's webhook auth key, sent on every delivery so the subscriber can authenticate the sender. Rotate it with the regenerate-auth-key endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "X-Delivery-Attempt", "in": "header", "description": "1-based delivery attempt number. Greater than 1 indicates a retry after a previous non-2xx response or timeout; use it together with the CloudEvents `id` to de-duplicate.", "required": true, "schema": { "minimum": 1, "type": "integer", "format": "int32" } } ], "requestBody": { "description": "CloudEvents 1.0 envelope carrying the type-specific payload as `data`.", "content": { "application/cloudevents+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CloudEventEnvelope" }, { "required": [ "data" ], "type": "object", "properties": { "type": { "enum": [ "live.gps" ], "type": "string", "description": "Fixed CloudEvents type discriminator for this webhook." }, "data": { "$ref": "#/components/schemas/LiveGpsWebhookPayload" } } } ] } } }, "required": true }, "responses": { "200": { "description": "Delivery acknowledged. Return any 2xx to acknowledge receipt; a non-2xx response (or a timeout) causes the platform to retry delivery with back-off." } }, "security": [ ] } }, "journey.closed": { "description": "Journey closed", "post": { "tags": [ "Webhooks" ], "summary": "Journey closed", "description": "Fired when a journey completes (topic `journeys`). A lean summary; fetch the full journey via the journeys REST endpoints.", "operationId": "webhook_journey_closed", "parameters": [ { "name": "X-Webhook-Key", "in": "header", "description": "The organization's webhook auth key, sent on every delivery so the subscriber can authenticate the sender. Rotate it with the regenerate-auth-key endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "X-Delivery-Attempt", "in": "header", "description": "1-based delivery attempt number. Greater than 1 indicates a retry after a previous non-2xx response or timeout; use it together with the CloudEvents `id` to de-duplicate.", "required": true, "schema": { "minimum": 1, "type": "integer", "format": "int32" } } ], "requestBody": { "description": "CloudEvents 1.0 envelope carrying the type-specific payload as `data`.", "content": { "application/cloudevents+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CloudEventEnvelope" }, { "required": [ "data" ], "type": "object", "properties": { "type": { "enum": [ "journey.closed" ], "type": "string", "description": "Fixed CloudEvents type discriminator for this webhook." }, "data": { "$ref": "#/components/schemas/JourneyClosedWebhookPayload" } } } ] } } }, "required": true }, "responses": { "200": { "description": "Delivery acknowledged. Return any 2xx to acknowledge receipt; a non-2xx response (or a timeout) causes the platform to retry delivery with back-off." } }, "security": [ ] } }, "alarm.triggered": { "description": "Alarm triggered", "post": { "tags": [ "Webhooks" ], "summary": "Alarm triggered", "description": "Fired when a device raises an alarm (topic `alarms`).", "operationId": "webhook_alarm_triggered", "parameters": [ { "name": "X-Webhook-Key", "in": "header", "description": "The organization's webhook auth key, sent on every delivery so the subscriber can authenticate the sender. Rotate it with the regenerate-auth-key endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "X-Delivery-Attempt", "in": "header", "description": "1-based delivery attempt number. Greater than 1 indicates a retry after a previous non-2xx response or timeout; use it together with the CloudEvents `id` to de-duplicate.", "required": true, "schema": { "minimum": 1, "type": "integer", "format": "int32" } } ], "requestBody": { "description": "CloudEvents 1.0 envelope carrying the type-specific payload as `data`.", "content": { "application/cloudevents+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CloudEventEnvelope" }, { "required": [ "data" ], "type": "object", "properties": { "type": { "enum": [ "alarm.triggered" ], "type": "string", "description": "Fixed CloudEvents type discriminator for this webhook." }, "data": { "$ref": "#/components/schemas/AlarmTriggeredWebhookPayload" } } } ] } } }, "required": true }, "responses": { "200": { "description": "Delivery acknowledged. Return any 2xx to acknowledge receipt; a non-2xx response (or a timeout) causes the platform to retry delivery with back-off." } }, "security": [ ] } }, "event.generic": { "description": "Telematics event", "post": { "tags": [ "Webhooks" ], "summary": "Telematics event", "description": "Fired for telematics events (topic `events`). A trimmed public projection of the device event; internal fields are not included.", "operationId": "webhook_event_generic", "parameters": [ { "name": "X-Webhook-Key", "in": "header", "description": "The organization's webhook auth key, sent on every delivery so the subscriber can authenticate the sender. Rotate it with the regenerate-auth-key endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "X-Delivery-Attempt", "in": "header", "description": "1-based delivery attempt number. Greater than 1 indicates a retry after a previous non-2xx response or timeout; use it together with the CloudEvents `id` to de-duplicate.", "required": true, "schema": { "minimum": 1, "type": "integer", "format": "int32" } } ], "requestBody": { "description": "CloudEvents 1.0 envelope carrying the type-specific payload as `data`.", "content": { "application/cloudevents+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CloudEventEnvelope" }, { "required": [ "data" ], "type": "object", "properties": { "type": { "enum": [ "event.generic" ], "type": "string", "description": "Fixed CloudEvents type discriminator for this webhook." }, "data": { "$ref": "#/components/schemas/EventGenericWebhookPayload" } } } ] } } }, "required": true }, "responses": { "200": { "description": "Delivery acknowledged. Return any 2xx to acknowledge receipt; a non-2xx response (or a timeout) causes the platform to retry delivery with back-off." } }, "security": [ ] } }, "media.ready": { "description": "Media ready", "post": { "tags": [ "Webhooks" ], "summary": "Media ready", "description": "Fired when requested media is ready (topic `media`). Includes a SAS-signed `downloadUrl`; the raw blob URI is never sent.", "operationId": "webhook_media_ready", "parameters": [ { "name": "X-Webhook-Key", "in": "header", "description": "The organization's webhook auth key, sent on every delivery so the subscriber can authenticate the sender. Rotate it with the regenerate-auth-key endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "X-Delivery-Attempt", "in": "header", "description": "1-based delivery attempt number. Greater than 1 indicates a retry after a previous non-2xx response or timeout; use it together with the CloudEvents `id` to de-duplicate.", "required": true, "schema": { "minimum": 1, "type": "integer", "format": "int32" } } ], "requestBody": { "description": "CloudEvents 1.0 envelope carrying the type-specific payload as `data`.", "content": { "application/cloudevents+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/CloudEventEnvelope" }, { "required": [ "data" ], "type": "object", "properties": { "type": { "enum": [ "media.ready" ], "type": "string", "description": "Fixed CloudEvents type discriminator for this webhook." }, "data": { "$ref": "#/components/schemas/MediaReadyWebhookPayload" } } } ] } } }, "required": true }, "responses": { "200": { "description": "Delivery acknowledged. Return any 2xx to acknowledge receipt; a non-2xx response (or a timeout) causes the platform to retry delivery with back-off." } }, "security": [ ] } } } }