{ "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.", "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.uat.haloniq.com/", "description": "Haloniq Developer API" } ], "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 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": "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}/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 or device. A narrowing filter plus a date window is required, otherwise 400. Cursor-paginated.\n\n**Required scope:** `thirdparty.api.journeys_read`", "operationId": "get_v1_journeys", "parameters": [ { "name": "vehicle_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": "date_from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_to", "in": "query", "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 when no journey is 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.\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. When it already exists an If-Match header is required; a stale ETag 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" } } ], "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.\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" } } ], "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.\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" } } ], "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 previous key is invalidated immediately and the new raw key is returned exactly once.\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" } } } }, "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). Delivery URLs are SSRF-validated; 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" } } ], "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. 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" } } ], "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" ], "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" } } }, "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" ] }, "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", "hardware_id", "media" ], "type": "object", "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/VideoRequestStatus" }, "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, SSRF-blocked hosts rejected)" } } }, "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://identity.haloniq.com/connect/token", "refreshUrl": "https://identity.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": "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.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": [ ] } } } }