{ "openapi": "3.0.0", "paths": { "/v1/oauth/token": { "post": { "description": "Exchanges your client credentials for a short-lived bearer token.\n\nThis is the only unauthenticated endpoint in the API, and the entry point for every integration. Send `grant_type=client_credentials` as `application/x-www-form-urlencoded`, and authenticate either with HTTP Basic (client identifier as the username, client secret as the password) or by including `client_id` and `client_secret` in the body. Basic authentication is preferred: it keeps the secret out of request bodies that are more likely to be logged.\n\nTokens are valid for one hour. Request a new one when the current token expires rather than on every call — the token endpoint is rate-limited more aggressively than the rest of the API, and a client that mints a token per request will be throttled.\n\nScopes are described under Authentication in the guide above. If you omit the `scope` parameter you receive every scope your client is entitled to, which is the right default for most integrations.\n\n**Private beta.** Client credentials are issued manually to named integration partners. If you do not yet have them, write to dev@crashwise.app and describe the integration you have in mind.", "operationId": "OAuthController_token", "parameters": [ { "name": "Authorization", "in": "header", "description": "HTTP Basic credentials: `Basic base64(client_id:client_secret)`. Omit if you are sending the credentials in the request body instead.", "required": false, "schema": { "type": "string", "example": "Basic Y3dfY2xpZW50Ojk5OWM=" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequestDto" } } } }, "responses": { "200": { "description": "Credentials accepted. The response carries the access token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponseDto" } } } }, "400": { "description": "The request is malformed — a missing or unsupported `grant_type`, or a `scope` value your client does not hold. Returns `invalid_request`, `unsupported_grant_type`, or `invalid_scope`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorDto" } } } }, "401": { "description": "Client authentication failed. Returns `invalid_client`, and a `WWW-Authenticate: Basic realm=\"crashwise\"` header when credentials were supplied via HTTP Basic.", "headers": { "WWW-Authenticate": { "description": "Challenge for HTTP Basic authentication.", "schema": { "type": "string", "example": "Basic realm=\"crashwise\"" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorDto" } } } }, "429": { "description": "Too many token requests. Cache your access token for its full lifetime rather than requesting one per API call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorDto" } } } } }, "summary": "Obtain an access token", "tags": [ "OAuth" ], "security": [] } }, "/v1/reports/{id}/pdf": { "get": { "description": "Returns the accident report rendered as a PDF, generating it if it does not exist yet.\n\nThis is the unsigned document — the record as it currently stands. For the countersigned version, use the download endpoint instead. Generation for a report with many photographs can take a few seconds on first request; the result is then cached.", "operationId": "AccidentReportsController_getReportPdf", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "language", "required": false, "in": "query", "description": "Ignored. The report PDF is an organization document and always renders in the organization default language (CW-464). Kept for backward compatibility.", "schema": {} } ], "responses": { "200": { "description": "Report PDF", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Get the report PDF", "tags": [ "Accident Reports" ] } }, "/v1/reports": { "post": { "description": "Opens a new accident report in the draft state.\n\nMost integrations do not need this: reports are normally created by a driver in the Crashwise application at the scene, where photographs and the counterparty's details can actually be gathered. Create a report through the API when your own system is the point of first notification — a telematics crash alert, or a call handler taking the details by telephone.\n\nBecause an accident report has a human subject, supply `createdByUserId` identifying the driver it concerns. That user must belong to an organization your tenant owns.\n\nA report created here is a draft. It is not part of the documentation record until it is completed, and it can be freely amended until then.", "operationId": "AccidentReportsController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportDto" } } } }, "responses": { "201": { "description": "Report created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Create an accident report", "tags": [ "Accident Reports" ] }, "get": { "description": "Returns accident reports across every organization your tenant owns, most recent first.\n\nThis is the main entry point for keeping your own system in step with Crashwise. Filter by `organizationId` to scope to one fleet, by `organizationVehicleId` or `userId` to follow a particular vehicle or driver, and by `startDate` and `endDate` to fetch a window.\n\nFor incremental synchronisation, poll with a date range that overlaps your last successful run by a few minutes rather than starting exactly where you left off: a report saved while the previous page was being served would otherwise be missed.", "operationId": "AccidentReportsController_findAll", "parameters": [ { "name": "startDate", "required": false, "in": "query", "description": "Start date for filtering reports", "schema": { "example": "2024-01-01", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date for filtering reports", "schema": { "example": "2024-12-31", "type": "string" } }, { "name": "organizationId", "required": false, "in": "query", "description": "Organization ID to filter by", "schema": { "example": "54fa597c-3638-47e7-8208-ca9735288bbf", "type": "string" } }, { "name": "userId", "required": false, "in": "query", "description": "User ID to filter by", "schema": { "example": "54fa597c-3638-47e7-8208-ca9735288bbf", "type": "string" } }, { "name": "organizationVehicleId", "required": false, "in": "query", "description": "Organization Vehicle ID to filter by", "schema": { "example": "54fa597c-3638-47e7-8208-ca9735288bbf", "type": "string" } }, { "name": "location", "required": false, "in": "query", "description": "Location to filter by", "schema": { "example": "Vienna", "type": "string" } }, { "name": "lat", "required": false, "in": "query", "description": "Latitude for location-based search", "schema": { "example": 48.2082, "type": "number" } }, { "name": "lng", "required": false, "in": "query", "description": "Longitude for location-based search", "schema": { "example": 16.3738, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Order by field (default: created)", "schema": { "default": "created", "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort ascending (default: false, which means recent to old)", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "page", "required": false, "in": "query", "description": "Page number", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "example": 10, "type": "number" } }, { "name": "pageNumber", "required": false, "in": "query", "description": "Page number (alternative to page)", "schema": { "example": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Page size (alternative to limit)", "schema": { "example": 10, "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Paginated list of reports", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportDto" } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 42 }, "totalPages": { "type": "number", "example": 5 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List accident reports", "tags": [ "Accident Reports" ] } }, "/v1/reports/new": { "get": { "description": "Returns the reference data required to construct a valid accident report: the circumstance list, the vehicles and drivers available to the caller, and the currently supported document formats.\n\nUse this to populate a form rather than hard-coding option lists, which drift as jurisdictions and vehicle records change.", "operationId": "AccidentReportsController_getNewReportData", "parameters": [ { "name": "latitude", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "longitude", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Weather and address data", "content": { "application/json": { "schema": { "type": "object", "properties": { "weather": { "type": "object", "properties": { "airTemperature": { "type": "number" }, "windSpeed": { "type": "number" }, "symbolCode": { "type": "string" }, "conditions": { "type": "string" }, "precipitationAmount": { "type": "number" } } }, "address": { "type": "string" } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Get the data needed to open a report", "tags": [ "Accident Reports" ] } }, "/v1/reports/weather/history": { "get": { "description": "Returns the recorded weather at a given location and moment.\n\nThis exists because conditions at the time of an accident are frequently disputed and are rarely recorded accurately at the scene. Querying the historical record rather than asking a shaken driver to remember produces evidence that holds up better later.", "operationId": "AccidentReportsController_getHistoricalReportWeather", "parameters": [ { "name": "latitude", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "longitude", "required": true, "in": "query", "schema": { "type": "number" } }, { "name": "datetime", "required": true, "in": "query", "description": "Date and time of the accident in ISO 8601 format (e.g. 2024-01-01T12:30:00Z or with timezone offset)", "schema": { "example": "2024-01-01T12:30:00Z", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Historical weather data", "content": { "application/json": { "schema": { "type": "object", "properties": { "weather": { "type": "object", "properties": { "airTemperature": { "type": "number" }, "windSpeed": { "type": "number" }, "symbolCode": { "type": "string" }, "conditions": { "type": "string" }, "precipitationAmount": { "type": "number" } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Retrieve historical weather for a place and time", "tags": [ "Accident Reports" ] } }, "/v1/reports/organization/{organizationId}": { "get": { "description": "Returns reports belonging to a single organization. Equivalent to `GET /v1/reports` filtered by `organizationId`, and provided because scoping by fleet is the common case.\n\nIf the organization is not one your tenant owns the response is `404`, not `403` — see the tenancy section of the guide.", "operationId": "AccidentReportsController_findByOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReportDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List reports for one organization", "tags": [ "Accident Reports" ] } }, "/v1/reports/user/{userId}": { "get": { "description": "Returns reports concerning a single driver, most recent first. Useful for a driver record page in your own interface, or for assessing an individual's incident history.", "operationId": "AccidentReportsController_findByUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReportDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List reports for one driver", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}": { "get": { "description": "Returns the full report: the accident itself, the vehicles and people involved, the agreed circumstances, and references to the photographs, documents and sketch attached to it.\n\nThe list endpoints return a lighter representation. Fetch the report itself when you need the complete record — for example when opening a claim in your own system.", "operationId": "AccidentReportsController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Retrieve an accident report", "tags": [ "Accident Reports" ] }, "patch": { "description": "Amends a report that is still open. Send only the fields you are changing; omitted fields are left alone.\n\nOnce a report has been completed it is part of the documentation record, and once it has been signed the record and its generated PDF are fixed. Attempting to amend a signed report returns `409`.", "operationId": "AccidentReportsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReportDto" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Update an accident report", "tags": [ "Accident Reports" ] }, "delete": { "description": "Removes a report and everything attached to it — photographs, documents, messages and the sketch.\n\nThis is intended for abandoned drafts. A completed report is evidence: it may be relied on by an insurer or a court long after the incident, and deleting one destroys the counterparty's copy of a jointly agreed statement as well as your own. Consider whether your retention policy really calls for deletion rather than archival in your own system.", "operationId": "AccidentReportsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Delete an accident report", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/show": { "get": { "description": "Returns the detail of the signature process for a report — who was asked to sign, in what order, and what has happened so far.\n\nUse the status endpoint if you only need to know whether signing is finished; use this one to show a signer-by-signer breakdown.", "operationId": "AccidentReportsController_showReport", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Report document details", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "documentUrl": { "type": "string" }, "status": { "type": "string", "enum": [ "not_initiated", "pending", "completed", "cancelled" ] } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Get signature process details", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/sign": { "post": { "description": "Sends the completed report for signature by the parties involved and returns the URLs at which each of them signs.\n\nSigning is asynchronous and involves people: the URLs are opened by the drivers, not by your integration. Poll the signature status, and treat the report as final only once every signer has completed.\n\nA report must be completed before it can be signed.", "operationId": "AccidentReportsController_signReport", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignReportDto" } } } }, "responses": { "200": { "description": "Signature request initiated with signing links for driver and all opponents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignReportResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Start the signature process", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/share": { "post": { "description": "Emails the report to the recipients you name, or to the organization's stored share contacts if you name none.\n\nThe message carries a download link rather than an attachment, so a very large report with many photographs still arrives. Use the share-link endpoint instead if you want to distribute the link yourself.", "operationId": "AccidentReportsController_shareReport", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareReportDto" } } } }, "responses": { "200": { "description": "Report shared successfully" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Share a report by email", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/share-links": { "post": { "description": "Creates a link that lets someone download the report PDF without a Crashwise account — an insurer, a repairer, a solicitor.\n\nAnyone holding the link can download the report, so treat it as a credential: send it to a named recipient, not to a distribution list, and withdraw it when it is no longer needed.", "operationId": "AccidentReportsController_createShareLink", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "201": { "description": "Share link" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Create a download link", "tags": [ "Accident Reports" ] }, "delete": { "description": "Invalidates every download link issued for this report. Existing links stop working immediately.\n\nUse this when a link has been forwarded further than intended, or as a matter of routine once a claim is settled.", "operationId": "AccidentReportsController_revokeShareLinks", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Number of links withdrawn" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Withdraw download links", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/complete": { "post": { "description": "Closes documentation for a report, marking the record at the scene as finished.\n\nThis is the point at which a report stops being a draft. Required fields must be present and the parties must be recorded; if anything essential is missing the response is `422` naming the gaps. After completion the report can be signed, shared and filed, and substantive amendment is no longer possible.", "operationId": "AccidentReportsController_completeReport", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteReportDto" } } } }, "responses": { "200": { "description": "Report closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteReportResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Complete the documentation", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/summary/regenerate": { "post": { "description": "Rebuilds the narrative summary of a completed report from its current contents.\n\nUseful after correcting a material detail — the summary is generated once at completion and does not otherwise track later edits. Regeneration replaces the previous summary rather than versioning it.", "operationId": "AccidentReportsController_regenerateSummary", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Summary regenerated" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Regenerate the report summary", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/download": { "get": { "description": "Returns the countersigned PDF for a report whose signature process has completed.\n\nThis is the document to file with an insurer: it carries the signatures of the parties and is what the e-signature process produced. If the report has not been signed the response is `409`; check the signature status first, or use the plain PDF endpoint for the unsigned record.", "operationId": "AccidentReportsController_downloadSignedReport", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Signed report PDF", "content": { "application/json": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Download the signed report PDF", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/signature-status": { "get": { "description": "Reports where each party has got to in the signature process, and whether the countersigned document is ready to download.\n\nPoll this after starting signature. Signing depends on people opening an email, so allow for hours or days rather than seconds, and back off accordingly.", "operationId": "AccidentReportsController_getSignatureStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Signature status with individual signer details", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_initiated", "pending", "completed", "cancelled" ] }, "signatureRequestId": { "type": "string" }, "documentId": { "type": "string" }, "signUrl": { "type": "string" }, "completed": { "type": "boolean" }, "signers": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "example": "john.doe@example.com" }, "signUrl": { "type": "string", "example": "https://signing.crashwise.app/s/abc123" }, "signed": { "type": "boolean", "example": false }, "nameIsPlaceholder": { "type": "boolean", "example": false, "description": "`role` is a generic stand-in (\"Other Driver\") because nobody recorded this party's name, rendered in the organization language. Clients should show their own translation instead. Absent for requests created before CW-1579." } } } }, "uninvitedSigners": { "type": "array", "description": "Parties whose signature line is printed but who were not invited, because their address already belongs to another signer. They never appear in `signers`.", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Jane Smith" }, "email": { "type": "string", "example": "office@example.com" }, "nameIsPlaceholder": { "type": "boolean", "example": false } } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Check signature progress", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/attachments": { "post": { "description": "Uploads an image, video or audio file and attaches it to the report.\n\nSubmit the file as `multipart/form-data`. Photographs intended as evidence are worth putting through validation first: a blurred or badly lit image is usually discovered to be useless weeks later, during a claim, when it can no longer be retaken.", "operationId": "AccidentReportsController_uploadAttachment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload and attach to the report (max 10 MB). Allowed types: images, videos, PDFs." }, "type": { "type": "string", "description": "Type/category of the attachment (e.g., photo, document, video)", "example": "photo" }, "title": { "type": "string", "description": "Optional title/label for the document (e.g., \"Police Report\", \"Dashcam Footage\")", "example": "Police Report" } } } } } }, "responses": { "201": { "description": "File uploaded and attached successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "accident_report_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440001" }, "uploaded_file_id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440002" }, "type": { "type": "string", "example": "photo" }, "name": { "type": "string", "example": "accident_photo.jpg" }, "created": { "type": "string", "example": "2024-01-01T00:00:00.000Z" }, "uploadedFile": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "example": "https://files.crashwise.app/ORG123/uploads/file.jpg" }, "thumbnailUrl": { "type": "string", "example": "https://files.crashwise.app/ORG123/uploads/file_thumb.jpg" } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Attach a photograph to a report", "tags": [ "Accident Reports" ] }, "get": { "description": "Returns the photographs and other media captured for this report, with their metadata and download references.\n\nThese are the evidential images taken at the scene — damage, positions, road markings — as distinct from paperwork, which is listed under documents.", "operationId": "AccidentReportsController_getAttachments", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of attachments", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "accident_report_id": { "type": "string" }, "uploaded_file_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "created": { "type": "string" }, "uploadedFile": { "type": "object", "properties": { "url": { "type": "string" }, "thumbnailUrl": { "type": "string" } } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List photographs attached to a report", "tags": [ "Accident Reports" ] } }, "/v1/reports/{id}/documents": { "post": { "description": "Uploads a document and files it against the report, as `multipart/form-data`.\n\nUse this for material that accumulates after the incident: estimates, invoices, insurer correspondence. Give each one a meaningful title — it is what appears in the documents overview, and an untitled file is close to useless six months later.", "operationId": "AccidentReportsController_uploadDocument", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Document file (max 10MB)" }, "title": { "type": "string", "description": "Optional display title for the document" }, "description": { "type": "string", "description": "Optional free-text description for the document" } } } } } }, "responses": { "201": { "description": "Document successfully uploaded and attached" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Attach a document to a report", "tags": [ "Accident Reports" ] }, "get": { "description": "Returns the paperwork associated with the report — repair estimates, correspondence, police references — with titles and descriptions.\n\nDistinct from attachments, which are the media captured at the scene.", "operationId": "AccidentReportsController_getDocuments", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of documents for the report" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List documents attached to a report", "tags": [ "Accident Reports" ] } }, "/v1/reports/documents/{attachmentId}/download": { "get": { "description": "Returns the document's bytes, with the content type it was uploaded as.\n\nStream the response rather than buffering it — documents attached to a report have no small fixed upper bound.", "operationId": "AccidentReportsController_downloadDocument", "parameters": [ { "name": "attachmentId", "required": true, "in": "path", "description": "Attachment ID", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Document file stream" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Download a document", "tags": [ "Accident Reports" ] } }, "/v1/reports/documents/{attachmentId}": { "patch": { "description": "Updates a document's title and description. The file itself is unchanged; to replace the content, upload a new document and delete the old one.", "operationId": "AccidentReportsController_updateDocument", "parameters": [ { "name": "attachmentId", "required": true, "in": "path", "description": "Attachment ID", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentDto" } } } }, "responses": { "200": { "description": "Document updated" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Rename or re-describe a document", "tags": [ "Accident Reports" ] }, "delete": { "description": "Removes a document from its report, deleting the underlying file. Irreversible.", "operationId": "AccidentReportsController_deleteDocument", "parameters": [ { "name": "attachmentId", "required": true, "in": "path", "description": "Attachment ID", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Document deleted successfully" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Delete a document", "tags": [ "Accident Reports" ] } }, "/v1/reports/attachments/{attachmentId}": { "delete": { "description": "Removes a photograph or media file from its report.\n\nIrreversible, and the underlying file is deleted rather than hidden. A photograph taken at a scene cannot be recaptured.", "operationId": "AccidentReportsController_deleteAttachment", "parameters": [ { "name": "attachmentId", "required": true, "in": "path", "description": "Attachment ID", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Attachment deleted successfully" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Delete an attachment", "tags": [ "Accident Reports" ] } }, "/v1/circumstance-types": { "get": { "description": "Returns the standardised circumstances used on the European Accident Statement — manoeuvring, changing lanes, reversing, and so on.\n\nThese are the tick-boxes both drivers agree at the scene, and they carry legal weight. Present the canonical list rather than your own paraphrase; the wording is standardised for a reason.", "operationId": "CircumstanceTypesController_getCircumstanceTypes", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "lang", "required": false, "in": "query", "description": "Language code for translations (e.g. en, de, fr, hr). Also resolved from Accept-Language or x-language header.", "schema": { "example": "en" } } ], "responses": { "200": { "description": "Returns a paginated list of circumstance types.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "example": 1 }, "code": { "type": "string", "example": "parked" }, "name": { "type": "string", "example": "Parked (at the roadside)" }, "display_order": { "type": "number", "example": 1 } } } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 17 }, "totalPages": { "type": "number", "example": 2 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [] } ], "summary": "List accident circumstances", "tags": [ "Circumstance Types" ] } }, "/v1/circumstance-types/{id}": { "get": { "description": "Returns one circumstance with its standard wording and translations.", "operationId": "CircumstanceTypesController_getCircumstanceTypeById", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "lang", "required": false, "in": "query", "description": "Language code for translations", "schema": { "example": "en" } } ], "responses": { "200": { "description": "Returns the circumstance with the specified ID." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [] } ], "summary": "Retrieve a circumstance", "tags": [ "Circumstance Types" ] } }, "/v1/crash-assistant/sessions": { "post": { "description": "Opens a session that walks a driver through documenting an accident, one step at a time.\n\nUse this to embed the guided flow in your own application rather than sending drivers to ours. The session decides what to ask next based on what has been answered so far, so drive your interface from the returned step rather than from a fixed script of your own.", "operationId": "CrashAssistantController_createSession", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionDto" } } } }, "responses": { "201": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Start a guided documentation session", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/sessions/{id}": { "get": { "description": "Returns the current step, what has been answered, and how much of the documentation remains.\n\nFetch this when resuming — an accident scene is not a place where an application stays in the foreground, and sessions are routinely picked up again after an interruption.", "operationId": "CrashAssistantController_getSession", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Session UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "Get session state", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/sessions/{id}/link-report": { "post": { "description": "Associates an existing accident report with a session that has none, so that answers gathered in the session are written to that report.\n\nUse this where documentation began before the report existed — a driver starting the guided flow on the way to the scene, for instance.", "operationId": "CrashAssistantController_linkReport", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Session UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkReportDto" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkReportResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Attach a report to a session", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/sessions/{id}/answer-text": { "post": { "description": "Submits a typed answer and advances the session, returning the next step.", "operationId": "CrashAssistantController_answerText", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Session UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerTextDto" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Answer the current step with text", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/sessions/{id}/answer-audio": { "post": { "description": "Submits a spoken answer, which is transcribed and applied to the current step.\n\nOften the only workable input at a scene: hands are occupied, the weather is poor, and typing accurately is more than can reasonably be expected of someone who has just had a collision.", "operationId": "CrashAssistantController_answerAudio", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Session UUID", "schema": { "type": "string" } }, { "name": "token", "required": false, "in": "query", "description": "JWT token as query param for FormData requests", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "idempotencyKey": { "type": "string" }, "enableTTS": { "type": "boolean" }, "engine": { "type": "string" }, "speechRate": { "type": "string" }, "voiceId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Answer the current step by voice", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/sessions/{id}/answer-widget": { "post": { "description": "Submits the result of a structured control — a selection, a position, a set of choices — for steps that ask for something more specific than free text.", "operationId": "CrashAssistantController_answerWidget", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Session UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerWidgetDto" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Answer the current step with structured input", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/sessions/{id}/skip": { "post": { "description": "Moves past a step without answering it.\n\nSome things genuinely cannot be captured — the other driver has left, the damage is not visible in the dark. A skipped step is recorded as skipped rather than as absent, which is a materially better position later than a silent gap.", "operationId": "CrashAssistantController_skipStep", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Session UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Skip the current step", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/sessions/{id}/back": { "post": { "description": "Returns to the previous step so an answer can be revised. The answer being revisited is retained, so a person correcting one detail does not have to re-enter the rest.", "operationId": "CrashAssistantController_goBack", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Session UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Go back a step", "tags": [ "Crash Assistant" ] } }, "/v1/crash-assistant/voices": { "get": { "description": "Returns the voices available for reading steps aloud, with their languages.\n\nSpoken prompts matter more here than in most applications: the person following them is standing at the roadside and is not necessarily in a state to read carefully.", "operationId": "CrashAssistantController_getVoices", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "List available voices", "tags": [ "Crash Assistant" ] } }, "/v1/driving-licences": { "post": { "description": "Files a licence against a user, with its category entitlements and expiry date.\n\nYou can capture these details by photographing the document rather than typing them — see the licence scan endpoint under Files.", "operationId": "DrivingLicencesController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDrivingLicenceDto" } } } }, "responses": { "201": { "description": "Driving licence successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrivingLicenceDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:write" ] } ], "summary": "Record a driving licence", "tags": [ "Driving Licences" ] }, "get": { "description": "Returns licences across the users in your organizations. Useful for an expiry report: a lapsed licence is both a compliance problem and, after an accident, an insurance one.", "operationId": "DrivingLicencesController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Paginated list of driving licences", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DrivingLicenceDto" } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 42 }, "totalPages": { "type": "number", "example": 5 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:read" ] } ], "summary": "List driving licences", "tags": [ "Driving Licences" ] } }, "/v1/driving-licences/user/{userId}": { "get": { "description": "Returns the licences recorded against one person. More than one is normal where a driver holds separate national and vocational entitlements.", "operationId": "DrivingLicencesController_findByUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of driving licences for the user", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DrivingLicenceDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:read" ] } ], "summary": "List a user's licences", "tags": [ "Driving Licences" ] } }, "/v1/driving-licences/{uuid}": { "get": { "description": "Returns one licence record in full.", "operationId": "DrivingLicencesController_findOne", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Driving licence UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Driving licence details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrivingLicenceDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:read" ] } ], "summary": "Retrieve a driving licence", "tags": [ "Driving Licences" ] }, "patch": { "description": "Amends a licence record — most often to extend the expiry date after renewal, or to correct a field that was misread from a photograph.", "operationId": "DrivingLicencesController_update", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Driving licence UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDrivingLicenceDto" } } } }, "responses": { "200": { "description": "Driving licence successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrivingLicenceDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:write" ] } ], "summary": "Update a driving licence", "tags": [ "Driving Licences" ] }, "delete": { "description": "Removes a licence record. Use this to correct a record filed against the wrong person; superseded licences are better updated than deleted, since the history is sometimes relevant.", "operationId": "DrivingLicencesController_remove", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Driving licence UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Driving licence successfully deleted" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:write" ] } ], "summary": "Delete a driving licence", "tags": [ "Driving Licences" ] } }, "/v1/files/upload": { "post": { "description": "Uploads an image, video or audio file and returns a reference you can attach to a report.\n\nSubmit as `multipart/form-data`. Use this when you want to upload first and decide where the file belongs afterwards; to upload and attach in one step, post directly to the report's attachments.", "operationId": "FilesController_uploadFile", "parameters": [ { "name": "guestToken", "required": false, "in": "query", "description": "Guest token for opponent/witness uploads", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File to upload" }, "caption": { "type": "string", "description": "Optional caption for the upload" } } } } } }, "responses": { "200": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Upload a file", "tags": [ "Files" ] } }, "/v1/files/drivers-license-scan": { "post": { "description": "Extracts the structured fields from a photograph of a driving licence — name, date of birth, licence number, categories and expiry.\n\nThis is markedly more reliable than asking someone to type a licence number at the roadside, and it is considerably faster. Treat the result as a draft to be confirmed rather than as verified fact: a rain-spotted licence photographed in poor light will produce plausible and wrong output.", "operationId": "FilesController_scanDriversLicense", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Driver's license image (JPEG or PNG, max 5MB)" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 of the issuing country. Optional — it sharpens the rules for which categories the holder actually has on older paper licences." } } } } } }, "responses": { "200": { "description": "Driver's license scanned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriversLicenseScanResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Read a driving licence from a photograph", "tags": [ "Files" ] } }, "/v1/files/license-plate-scan": { "post": { "description": "Extracts a vehicle registration number from a photograph of the plate.\n\nUseful for confirming an opponent's vehicle without relying on a number written down at the scene, where transposed characters are common.", "operationId": "FilesController_scanLicensePlate", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "License plate image" } } } } } }, "responses": { "200": { "description": "License plate scanned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensePlateScanResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Read a registration plate from a photograph", "tags": [ "Files" ] } }, "/v1/files/document-profiles": { "get": { "description": "Returns the registration-document formats recognised by the scanning endpoints, by country.\n\nConsult this before reporting a scan as broken — an unrecognised format is far more often the cause than a failure of the scan itself.", "operationId": "FilesController_getDocumentProfiles", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Catalogue of document profiles" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "List supported document formats", "tags": [ "Files" ] } }, "/v1/files/vehicle-registration-scan": { "post": { "description": "Extracts the vehicle and keeper details from a photograph of a registration certificate.\n\nFormats differ substantially between countries; check the supported formats endpoint if a document from a particular jurisdiction is not being read.", "operationId": "FilesController_scanVehicleRegistration", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "minItems": 1, "maxItems": 4, "description": "1-4 images of a vehicle registration certificate (both sides, or the sections of a folded sheet)" }, "ocrText": { "type": "string", "description": "Optional OCR text to supplement image analysis" } } } } } }, "responses": { "200": { "description": "Vehicle registration data extracted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleScanResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Read a vehicle registration document", "tags": [ "Files" ] } }, "/v1/files/insurance-card-scan": { "post": { "description": "Extracts the insurer, policy number and covered vehicle from a photograph of an insurance card or green card.\n\nThe most common use is capturing the opponent's cover at the scene, where the card is available for a few minutes and the details are otherwise copied out by hand under pressure.", "operationId": "FilesController_scanInsuranceCard", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Insurance card image (JPEG or PNG, max 5MB)" } } } } } }, "responses": { "200": { "description": "Insurance card scanned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsuranceCardScanResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Read an insurance card from a photograph", "tags": [ "Files" ] } }, "/v1/health": { "get": { "description": "Returns the service's current status. Suitable as a connectivity check from your monitoring.\n\nIt reports whether the API is reachable and serving, which is not the same as whether your credentials work; a `200` here alongside a `401` elsewhere means your token needs attention, not us.", "operationId": "HealthController_check", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "The Health Check is successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "info": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "error": { "type": "object", "example": {}, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true }, "nullable": true }, "details": { "type": "object", "example": { "database": { "status": "up" } }, "additionalProperties": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } }, "additionalProperties": true } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [] } ], "summary": "Check service health", "tags": [ "Health" ] } }, "/v1/insurance-lookup": { "post": { "description": "Resolves the insurer covering a vehicle from its registration number.\n\nUsed to normalise an opponent's cover rather than storing whatever they said at the scene. Coverage varies by country, and a lookup that finds nothing is not evidence that the vehicle is uninsured.", "operationId": "InsuranceLookupController_lookup", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsuranceLookupRequestDto" } } } }, "responses": { "200": { "description": "Insurance lookup result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsuranceLookupResponseDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [] } ], "summary": "Look up an insurer by registration plate", "tags": [ "Insurance Lookup" ] } }, "/v1/issue-reports": { "post": { "description": "Submits a problem report from inside your integration.\n\nInclude the `requestId` from any failed response — it is what lets us find the corresponding entry in our logs, and a report without one takes considerably longer to act on.", "operationId": "IssueReportsController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIssueReportDto" } } } }, "responses": { "201": { "description": "Issue report stored", "content": { "application/json": { "schema": { "example": { "id": "550e8400-e29b-41d4-a716-446655440000", "ticketNumber": "ISS-1042", "createdAt": "2026-06-22T09:15:42.123Z" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [] } ], "summary": "Report a problem", "tags": [ "Issue Reports" ] } }, "/v1/messages": { "post": { "description": "Sends a message to drivers in your organizations, either immediately or at a future time.\n\nUse it for operational notices that belong alongside accident documentation — a change to the reporting procedure, a reminder to complete an outstanding report. Schedule rather than send if the message is time-sensitive: a notice that arrives at three in the morning is a notice that gets dismissed.", "operationId": "MessagesController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessageDto" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Send or schedule a message", "tags": [ "Messages" ] }, "get": { "description": "Returns messages sent or scheduled by your tenant, with their current delivery state. Scheduled messages appear here before they go out and can be cancelled until then.", "operationId": "MessagesController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "status", "required": false, "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "draft", "scheduled", "sending", "sent", "cancelled" ] } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List messages you have sent", "tags": [ "Messages" ] } }, "/v1/messages/{id}": { "get": { "description": "Returns one message with its delivery statistics — how many recipients it reached and how many have read it.", "operationId": "MessagesController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Message UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Retrieve a message", "tags": [ "Messages" ] }, "delete": { "description": "Removes a message and every recipient record for it, including from inboxes where it has already been delivered and read.\n\nThis erases the fact that the message was ever sent. If your reason is that the content was wrong, sending a correction is usually the better course — deleting the original leaves no record that recipients acted on it.", "operationId": "MessagesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Message UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Delete a message", "tags": [ "Messages" ] } }, "/v1/messages/{id}/cancel": { "patch": { "description": "Stops a scheduled message from being sent. Only works while it is still pending; once delivery has begun the response is `409`, and a message cannot be recalled from an inbox it has already reached.", "operationId": "MessagesController_cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Message UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Cancel a scheduled message", "tags": [ "Messages" ] } }, "/v1/organizations": { "post": { "description": "Creates a new organization under your tenant — typically one per customer fleet.\n\nAn organization is the unit that owns vehicles, users and accident reports. Everything else in this API belongs to exactly one of them, so this is usually the first call a new integration makes.", "operationId": "OrganizationsController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationDto" } } } }, "responses": { "201": { "description": "Organization successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:write" ] } ], "summary": "Create an organization", "tags": [ "Organizations" ] }, "get": { "description": "Returns every organization your tenant owns. Organizations belonging to other tenants are not visible and are not distinguishable from ones that do not exist.", "operationId": "OrganizationsController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "search", "required": false, "in": "query", "description": "Search term to filter organizations by name or code. Space-separated tokens must all match; either field may satisfy a token.", "schema": { "example": "acme berlin", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Paginated list of organizations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationDto" } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 42 }, "totalPages": { "type": "number", "example": 5 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:read" ] } ], "summary": "List organizations", "tags": [ "Organizations" ] } }, "/v1/organizations/code/{code}": { "get": { "description": "Finds an organization by its short human-readable code rather than its identifier.\n\nUseful when the code is what your own system stores, or what a person quotes over the telephone.", "operationId": "OrganizationsController_findByCode", "parameters": [ { "name": "code", "required": true, "in": "path", "description": "Organization code (8 characters)", "schema": { "example": "CRASHWIS", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:read" ] } ], "summary": "Look up an organization by code", "tags": [ "Organizations" ] } }, "/v1/organizations/{uuid}": { "get": { "description": "Returns one organization's details and settings.", "operationId": "OrganizationsController_findOne", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Organization UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:read" ] } ], "summary": "Retrieve an organization", "tags": [ "Organizations" ] }, "patch": { "description": "Amends an organization's details. Send only the fields you are changing.", "operationId": "OrganizationsController_update", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Organization UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationDto" } } } }, "responses": { "200": { "description": "Organization successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:write" ] } ], "summary": "Update an organization", "tags": [ "Organizations" ] }, "delete": { "description": "Removes an organization.\n\nThis is the most destructive operation in the API: an organization owns vehicles, users and accident reports, and removing it takes the fleet and its documentation history with it. Verify the identifier before calling, and prefer emptying an organization you might need again over deleting it.", "operationId": "OrganizationsController_remove", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Organization UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Organization successfully deleted" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:write" ] } ], "summary": "Delete an organization", "tags": [ "Organizations" ] } }, "/v1/organizations/{uuid}/notification-settings": { "get": { "description": "Returns who is emailed when a new accident report is filed for this organization.", "operationId": "OrganizationsController_getNotificationSettings", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Organization UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Notification settings" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:read" ] } ], "summary": "Get new-report notification settings", "tags": [ "Organizations" ] }, "patch": { "description": "Changes who is emailed when a new accident report is filed.\n\nWorth pointing at a monitored shared mailbox rather than a named individual: accidents do not wait for people to come back from leave.", "operationId": "OrganizationsController_updateNotificationSettings", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Organization UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNotificationSettingsDto" } } } }, "responses": { "200": { "description": "Notification settings updated" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:write" ] } ], "summary": "Update new-report notification settings", "tags": [ "Organizations" ] } }, "/v1/organizations/{uuid}/share-contacts": { "get": { "description": "Returns the recipients a completed report is sent to when it is shared without explicit addressees — usually the fleet's insurer or broker.", "operationId": "OrganizationsController_getShareContacts", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Organization UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Share contacts" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:read" ] } ], "summary": "Get default share recipients", "tags": [ "Organizations" ] }, "patch": { "description": "Sets the default recipients for shared reports. Keep this current: a report shared to a broker who no longer handles the account is a claim that quietly goes nowhere.", "operationId": "OrganizationsController_updateShareContacts", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Organization UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShareContactsDto" } } } }, "responses": { "200": { "description": "Share contacts updated" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "organizations:write" ] } ], "summary": "Update default share recipients", "tags": [ "Organizations" ] } }, "/v1/photos/{photoId}/validate": { "post": { "description": "Checks whether a photograph is usable as evidence: sharp enough, adequately lit, and actually showing what the documentation step asked for.\n\nRun this at the moment of capture, while the vehicle is still there. The alternative is discovering during a claim, weeks later, that the only photograph of the damage is unusable.", "operationId": "PhotoValidationController_validate", "parameters": [ { "name": "photoId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatePhotoDto" } } } }, "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Validate a photograph", "tags": [ "Photo Validation" ] } }, "/v1/reports/{reportId}/photos/pending-review": { "get": { "description": "Returns photographs that validation has flagged as possibly unusable and that nobody has yet resolved.\n\nSurface these before a report is completed, so a driver can retake a photograph rather than a claims handler discovering the gap later.", "operationId": "PhotoValidationController_pendingReview", "parameters": [ { "name": "reportId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PendingReviewPhotoDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "List photographs awaiting review", "tags": [ "Photo Validation" ] } }, "/v1/photos/{photoId}/validation/skip": { "post": { "description": "Records that a person has looked at a flagged photograph and decided to keep it, removing it from the review list.\n\nValidation is advisory. A photograph can be technically poor and still be the only evidence that exists, and a person is better placed than an automated check to make that judgement.", "operationId": "PhotoValidationController_skip", "parameters": [ { "name": "photoId", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Keep a flagged photograph", "tags": [ "Photo Validation" ] } }, "/v1/reports/{reportId}/opponents": { "post": { "description": "Records another party to the accident: their vehicle, their insurer, and how to contact them.\n\nOpponent records belong to one report and are not shared between reports, because the same registration plate may be insured differently on different dates. Capturing the policy details as they stood at the moment of the accident is the entire point.\n\nInvitations that let an opponent fill in their own details are issued through the Crashwise applications and are not available here.", "operationId": "ReportOpponentsController_create", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportOpponentDto" } } } }, "responses": { "201": { "description": "Opponent added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOpponentDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Add an opponent to a report", "tags": [ "Report Opponents" ] }, "get": { "description": "Returns every other party recorded against this accident. Most accidents have one; multi-vehicle incidents have several.", "operationId": "ReportOpponentsController_findAll", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of opponents", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReportOpponentDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List opponents on a report", "tags": [ "Report Opponents" ] } }, "/v1/reports/{reportId}/opponents/{id}": { "get": { "description": "Returns one opponent record in full, including the insurance details captured for their vehicle.", "operationId": "ReportOpponentsController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Opponent UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": {} } ], "responses": { "200": { "description": "Opponent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOpponentDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Retrieve an opponent", "tags": [ "Report Opponents" ] }, "patch": { "description": "Corrects an opponent's details. Send only the fields you are changing.\n\nCommonly used to complete a record after the fact — policy numbers in particular are often illegible at the scene and confirmed later by the insurer.", "operationId": "ReportOpponentsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Opponent UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": {} } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReportOpponentDto" } } } }, "responses": { "200": { "description": "Opponent updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportOpponentDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Update an opponent", "tags": [ "Report Opponents" ] }, "delete": { "description": "Deletes an opponent record from the report. Use this to correct a mistaken entry, not to resolve a dispute about liability — the record is a statement of who was present, not of who was at fault.", "operationId": "ReportOpponentsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Opponent UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": {} } ], "responses": { "200": { "description": "Opponent deleted successfully" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Remove an opponent", "tags": [ "Report Opponents" ] } }, "/v1/reports/{reportId}/witnesses": { "post": { "description": "Records someone who saw the accident but was not involved in it, together with their statement and contact details.\n\nWitnesses are recorded at the scene because that is the only moment they are reliably available. A witness whose telephone number was not taken is, in practice, not a witness at all.", "operationId": "ReportWitnessesController_create", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWitnessDto" } } } }, "responses": { "201": { "description": "Witness added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WitnessDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Add a witness to a report", "tags": [ "Report Witnesses" ] }, "get": { "description": "Returns every witness recorded against this accident.", "operationId": "ReportWitnessesController_findAll", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of witnesses", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WitnessDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "List witnesses on a report", "tags": [ "Report Witnesses" ] } }, "/v1/reports/{reportId}/witnesses/{id}": { "get": { "description": "Returns one witness record, including their statement as it was taken.", "operationId": "ReportWitnessesController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Witness ID", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": {} } ], "responses": { "200": { "description": "Witness details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WitnessDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Retrieve a witness", "tags": [ "Report Witnesses" ] }, "patch": { "description": "Corrects a witness record — most often a contact detail taken down wrongly in the moment.", "operationId": "ReportWitnessesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Witness ID", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": {} } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWitnessDto" } } } }, "responses": { "200": { "description": "Witness updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WitnessDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Update a witness", "tags": [ "Report Witnesses" ] }, "delete": { "description": "Deletes a witness record from the report. Irreversible, and the statement goes with it.", "operationId": "ReportWitnessesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Witness ID", "schema": { "type": "number" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": {} } ], "responses": { "200": { "description": "Witness deleted successfully" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Remove a witness", "tags": [ "Report Witnesses" ] } }, "/v1/reports/{reportId}/sketch": { "post": { "description": "Creates a sketch for the report, or rebuilds an existing one from the report's current contents — the accident location, the road layout there, and the vehicles recorded.\n\nRebuilding discards manual edits made to the editable layers. Update those layers directly if you want to preserve them.", "operationId": "SketchController_generateSketch", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateSketchDto" } } } }, "responses": { "200": { "description": "Sketch created or refreshed" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Create or rebuild the scene sketch", "tags": [ "Sketch" ] }, "get": { "description": "Returns the scene diagram as structured data — road layout, vehicle positions, and directions of travel at the moment of impact.\n\nBecause it is data rather than a flat image, you can re-render it at any size, restyle it to match your own interface, or inspect the geometry programmatically.", "operationId": "SketchController_getSketch", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "layers", "required": false, "in": "query", "description": "`full` (default): baked SVG. `base`: aerial + roads only, with vehicles/arrows/annotations returned as JSON for client-side editing.", "schema": { "enum": [ "full", "base" ], "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Sketch data" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:read" ] } ], "summary": "Retrieve the scene sketch", "tags": [ "Sketch" ] }, "patch": { "description": "Applies changes to the parts of the sketch a person is allowed to move: vehicle positions, arrows, annotations.\n\nThe underlying road layout is derived from the accident location and is not editable here — a sketch that contradicts the map would undermine the document it belongs to.", "operationId": "SketchController_updateSketch", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSketchDto" } } } }, "responses": { "200": { "description": "Updated sketch" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Update the editable layers", "tags": [ "Sketch" ] } }, "/v1/reports/{reportId}/sketch/place-vehicles": { "post": { "description": "Positions the vehicles on the sketch from the recorded circumstances and the road layout, producing a starting arrangement for someone to adjust.\n\nA first approximation, not a finding. The parties should confirm the positions before the report is completed.", "operationId": "SketchController_placeVehicles", "parameters": [ { "name": "reportId", "required": true, "in": "path", "description": "Report UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Sketch with placed vehicles" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "reports:write" ] } ], "summary": "Place vehicles on the sketch automatically", "tags": [ "Sketch" ] } }, "/v1/user-uploads": { "post": { "description": "Registers a piece of media captured during documentation — a photograph, a video, or an audio note.\n\nAudio uploads are transcribed asynchronously: create the record, then poll for the transcription rather than expecting text in this response.", "operationId": "UploadsController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadDto" } } } }, "responses": { "201": { "description": "Upload successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Create an upload record", "tags": [ "Uploads" ] }, "get": { "description": "Returns media uploaded across your organizations, with storage accounting and, for audio, transcription state.", "operationId": "UploadsController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Paginated list of uploads", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UploadDto" } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 42 }, "totalPages": { "type": "number", "example": 5 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "List uploads", "tags": [ "Uploads" ] } }, "/v1/user-uploads/user/{userId}": { "get": { "description": "Returns media uploaded by one person.", "operationId": "UploadsController_findByUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of uploads for the user", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "List a user's uploads", "tags": [ "Uploads" ] } }, "/v1/user-uploads/organization/{organizationId}": { "get": { "description": "Returns media uploaded across one organization. Useful alongside the storage statistics when reviewing consumption.", "operationId": "UploadsController_findByOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440002", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of uploads for the organization", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "List an organization's uploads", "tags": [ "Uploads" ] } }, "/v1/user-uploads/transcript-status/{status}": { "get": { "description": "Returns audio uploads in a given transcription state.\n\nThe practical use is finding work that has stalled: query the pending state periodically and investigate anything that has been sitting there far longer than a transcription takes.", "operationId": "UploadsController_findByTranscriptStatus", "parameters": [ { "name": "status", "required": true, "in": "path", "description": "Transcript status", "schema": { "enum": [ "D", "N", "P", "E" ], "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of uploads with the specified status", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UploadDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "List uploads by transcription state", "tags": [ "Uploads" ] } }, "/v1/user-uploads/stats/{userId}": { "get": { "description": "Returns how much storage one person's uploads occupy, broken down by media type. Video dominates in practice.", "operationId": "UploadsController_getStorageStats", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440001", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Storage statistics" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "Get storage statistics for a user", "tags": [ "Uploads" ] } }, "/v1/user-uploads/{uuid}": { "get": { "description": "Returns one upload with its metadata and, where applicable, its transcription.", "operationId": "UploadsController_findOne", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "uuid", "required": true, "in": "path", "description": "Upload UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Upload details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:read" ] } ], "summary": "Retrieve an upload", "tags": [ "Uploads" ] }, "patch": { "description": "Amends an upload's metadata. The stored media itself is immutable — to replace it, create a new upload and delete the old one.", "operationId": "UploadsController_update", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "uuid", "required": true, "in": "path", "description": "Upload UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUploadDto" } } } }, "responses": { "200": { "description": "Upload successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Update an upload", "tags": [ "Uploads" ] }, "delete": { "description": "Removes an upload and the underlying media. Irreversible. If the upload is attached to a completed report, consider whether the report still stands without it.", "operationId": "UploadsController_remove", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "uuid", "required": true, "in": "path", "description": "Upload UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Upload successfully deleted" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Delete an upload", "tags": [ "Uploads" ] } }, "/v1/user-uploads/{uuid}/transcription": { "patch": { "description": "Replaces the transcription held against an audio upload.\n\nUse this to correct a transcript where the automatic result is wrong — background noise at an accident scene is not kind to speech recognition, and a corrected transcript is worth more than an automatic one.", "operationId": "UploadsController_updateTranscription", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } }, { "name": "uuid", "required": true, "in": "path", "description": "Upload UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transcriptStatus": { "type": "string", "enum": [ "D", "N", "P", "E" ], "example": "D" }, "transcriptionJson": { "type": "object", "example": { "id": "25b30b7f-7bbd-49ec-9759-7275138b6496", "status": "completed" } }, "transcriptionText": { "type": "string", "example": "The transcribed text." } }, "required": [ "transcriptStatus" ] } } } }, "responses": { "200": { "description": "Transcription successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Update transcription data", "tags": [ "Uploads" ] } }, "/v1/user-uploads/{id}/poll-transcription": { "post": { "description": "Asks for the current state of an audio upload's transcription, returning the text once it is ready.\n\nPoll with backoff; transcription time scales with recording length.", "operationId": "UploadsController_pollTranscription", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Upload UUID", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Transcription status checked and updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "files:write" ] } ], "summary": "Check transcription progress", "tags": [ "Uploads" ] } }, "/v1/users": { "post": { "description": "Adds a person to one of your organizations — typically a driver, sometimes an administrator.\n\nA user must exist before they can be assigned a vehicle or named on an accident report, so user creation is normally the first step of onboarding a fleet.", "operationId": "UsersController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserDto" } } } }, "responses": { "201": { "description": "User created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:write" ] } ], "summary": "Create a user", "tags": [ "Users" ] }, "get": { "description": "Returns users across every organization your tenant owns. Filter by `organizationId` for one fleet.", "operationId": "UsersController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "organizationId", "required": false, "in": "query", "description": "Organization ID to filter by", "schema": { "example": "54fa597c-3638-47e7-8208-ca9735288bbf", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Paginated list of users", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UserDto" } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 42 }, "totalPages": { "type": "number", "example": 5 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:read" ] } ], "summary": "List users", "tags": [ "Users" ] } }, "/v1/users/import": { "post": { "description": "Loads many users into an organization in one call — the counterpart of the vehicle import, and the usual way to onboard a fleet.\n\nSend an `Idempotency-Key`; the retry argument is the same as for vehicles, with the added nuisance that duplicate people are harder to spot than duplicate registration plates.", "operationId": "UsersController_import", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportUsersDto" } } } }, "responses": { "201": { "description": "Import results with created users and per-row errors" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:write" ] } ], "summary": "Import users in bulk", "tags": [ "Users" ] } }, "/v1/users/organization/{organizationId}": { "get": { "description": "Returns the people belonging to a single organization.", "operationId": "UsersController_findByOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of users in the organization", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:read" ] } ], "summary": "List users in one organization", "tags": [ "Users" ] } }, "/v1/users/{id}": { "get": { "description": "Returns one user's profile and the organization they belong to.", "operationId": "UsersController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:read" ] } ], "summary": "Retrieve a user", "tags": [ "Users" ] }, "patch": { "description": "Amends a user's details. Send only the fields you are changing.\n\nCredentials and second-factor settings are not managed through this API; a person changes those themselves in the Crashwise application.", "operationId": "UsersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserDto" } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:write" ] } ], "summary": "Update a user", "tags": [ "Users" ] }, "delete": { "description": "Removes a person from your organization.\n\nAccident reports they filed remain, and remain attributed to them: a report is a record of what happened and who documented it, and it does not become anonymous because someone has left the company.", "operationId": "UsersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "User UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "User deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "User deleted successfully" } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "users:write" ] } ], "summary": "Remove a user", "tags": [ "Users" ] } }, "/v1/vehicle-manufacturers": { "get": { "description": "Returns recognised manufacturers and their models.\n\nUse this to normalise vehicle records on entry. Free-text manufacturer fields produce fleets containing \"VW\", \"Volkswagen\" and \"volkswagen\" as three distinct makes, which makes every subsequent report unreliable.", "operationId": "VehicleManufacturersController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Paginated list of all manufacturers", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleManufacturerDto" } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 42 }, "totalPages": { "type": "number", "example": 5 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:read" ] } ], "summary": "List vehicle manufacturers", "tags": [ "Vehicle Manufacturers" ] } }, "/v1/vehicle-manufacturers/{id}": { "get": { "description": "Returns one manufacturer and the models recorded against it.", "operationId": "VehicleManufacturersController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Manufacturer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleManufacturerDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:read" ] } ], "summary": "Retrieve a manufacturer", "tags": [ "Vehicle Manufacturers" ] } }, "/v1/vehicles": { "post": { "description": "Adds one vehicle to an organization.\n\nRecord the insurance details along with the vehicle: they are copied onto an accident report at the moment a report is created, so a vehicle with no policy on file produces a report with a gap in it precisely when the gap matters most.\n\nUse `Idempotency-Key` — fleet synchronisations retry, and a duplicate vehicle is tedious to unpick.", "operationId": "VehiclesController_create", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVehicleDto" } } } }, "responses": { "201": { "description": "Vehicle created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:write" ] } ], "summary": "Add a vehicle", "tags": [ "Vehicles" ] }, "get": { "description": "Returns vehicles across every organization your tenant owns. Filter by `organizationId` for a single fleet.\n\nSortable by internal fleet number, registration number or creation date. Rows with no value in the sorted column are always listed last, so an unsorted-looking tail is expected rather than a fault.", "operationId": "VehiclesController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number (starts at 1)", "schema": { "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 10, "type": "number" } }, { "name": "orderBy", "required": false, "in": "query", "description": "Field to order by", "schema": { "example": "created", "type": "string" } }, { "name": "ascending", "required": false, "in": "query", "description": "Sort in ascending order", "schema": { "default": false, "example": false, "type": "boolean" } }, { "name": "organizationId", "required": false, "in": "query", "description": "Organization ID to filter by", "schema": { "example": "54fa597c-3638-47e7-8208-ca9735288bbf", "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search term to filter vehicles by manufacturer, model, registration number or internal vehicle number. Space-separated tokens must all match; the registration number and the internal vehicle number are compared ignoring case, spaces and hyphens.", "schema": { "example": "bmw x3", "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Paginated list of vehicles", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDto" } }, "meta": { "type": "object", "properties": { "page": { "type": "number", "example": 1 }, "limit": { "type": "number", "example": 10 }, "totalItems": { "type": "number", "example": 42 }, "totalPages": { "type": "number", "example": 5 }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { "type": "boolean", "example": false } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:read" ] } ], "summary": "List vehicles", "tags": [ "Vehicles" ] } }, "/v1/vehicles/import": { "post": { "description": "Loads many vehicles into an organization in a single call. This is the right tool for an initial fleet load or a scheduled reconciliation; the single-vehicle endpoints are for incremental changes.\n\nSend an `Idempotency-Key`. Bulk imports are exactly the calls that time out and get retried, and a partially applied duplicate import is a great deal of work to reverse.", "operationId": "VehiclesController_import", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportVehiclesDto" } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDto" } }, "updated": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDto" } }, "createdCount": { "type": "number", "example": 95 }, "updatedCount": { "type": "number", "example": 4 }, "failedCount": { "type": "number", "example": 1 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number", "example": 12 }, "message": { "type": "string", "example": "Missing organizationId" } } } }, "skippedCount": { "type": "number", "example": 0 }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number", "example": 42 }, "registrationNumber": { "type": "string", "example": "W-22627T" }, "reason": { "type": "string", "enum": [ "duplicate_vin" ] } } } } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:write" ] } ], "summary": "Import vehicles in bulk", "tags": [ "Vehicles" ] } }, "/v1/vehicles/delete-all": { "post": { "description": "Deletes the entire vehicle roster of one organization.\n\nIntended for a full re-synchronisation where your system is authoritative and the Crashwise copy is to be rebuilt from scratch. There is no undo and no confirmation step beyond this call, so guard it in your own code: an `organizationId` taken from the wrong variable empties the wrong customer's fleet.\n\nAccident reports are not affected.", "operationId": "VehiclesController_deleteAll", "parameters": [ { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAllVehiclesDto" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deletedCount": { "type": "number", "example": 254 } } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:write" ] } ], "summary": "Remove every vehicle from an organization", "tags": [ "Vehicles" ] } }, "/v1/vehicles/organization/{organizationId}": { "get": { "description": "Returns the vehicles belonging to a single organization. Equivalent to filtering the vehicle list, and provided because per-fleet listing is the common case.", "operationId": "VehiclesController_findByOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Organization UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleDto" } } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:read" ] } ], "summary": "List vehicles in one organization", "tags": [ "Vehicles" ] } }, "/v1/vehicles/assign/{driverId}": { "post": { "description": "Records which vehicles a driver is permitted to drive.\n\nAssignment determines which vehicle a driver can select when filing an accident report, so an unassigned driver is a driver who cannot document an incident. Keeping assignments current is the difference between a report filed at the scene and one reconstructed from memory the next day.", "operationId": "VehiclesController_assignVehiclesToDriver", "parameters": [ { "name": "driverId", "required": true, "in": "path", "description": "Driver UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Vehicles assigned successfully" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:write" ] } ], "summary": "Assign vehicles to a driver", "tags": [ "Vehicles" ] } }, "/v1/vehicles/assign/{driverId}/{vehicleId}": { "delete": { "description": "Removes one vehicle from a driver's assignments. Reports the driver has already filed against that vehicle are unaffected.", "operationId": "VehiclesController_removeVehicleAssignment", "parameters": [ { "name": "driverId", "required": true, "in": "path", "description": "Driver UUID", "schema": { "type": "string" } }, { "name": "vehicleId", "required": true, "in": "path", "description": "Vehicle UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:write" ] } ], "summary": "Unassign a vehicle from a driver", "tags": [ "Vehicles" ] } }, "/v1/vehicles/assignments/{driverId}": { "get": { "description": "Returns the vehicles currently assigned to a driver.", "operationId": "VehiclesController_getDriverAssignments", "parameters": [ { "name": "driverId", "required": true, "in": "path", "description": "Driver UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "List of vehicle assignments" }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:read" ] } ], "summary": "List a driver's vehicles", "tags": [ "Vehicles" ] } }, "/v1/vehicles/{uuid}": { "get": { "description": "Returns one vehicle in full: identification, technical specification and current insurance details.", "operationId": "VehiclesController_findOne", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Vehicle UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:read" ] } ], "summary": "Retrieve a vehicle", "tags": [ "Vehicles" ] }, "patch": { "description": "Amends a vehicle record. Send only the fields you are changing.\n\nUpdating insurance details affects reports created from now on; reports already filed keep the policy as it stood on the day of the accident, which is what an insurer will ask about.", "operationId": "VehiclesController_update", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Vehicle UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVehicleDto" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleDto" } } } }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "422": { "description": "The request body failed validation. The `errors` array names each offending field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:write" ] } ], "summary": "Update a vehicle", "tags": [ "Vehicles" ] }, "delete": { "description": "Removes a vehicle from the fleet. Accident reports that reference it are unaffected — they retain the vehicle details as recorded at the time of the incident.", "operationId": "VehiclesController_remove", "parameters": [ { "name": "uuid", "required": true, "in": "path", "description": "Vehicle UUID", "schema": { "type": "string" } }, { "name": "X-RateLimit-Limit", "in": "header", "description": "The number of requests permitted in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 600 } }, { "name": "X-RateLimit-Remaining", "in": "header", "description": "Requests remaining in the current rate-limit window.", "required": false, "schema": { "type": "integer", "example": 599 } }, { "name": "X-RateLimit-Reset", "in": "header", "description": "Unix timestamp, in seconds, at which the current rate-limit window resets.", "required": false, "schema": { "type": "integer", "example": 1755781200 } } ], "responses": { "200": { "description": "Success." }, "401": { "description": "The access token is missing, expired, or malformed. Obtain a new token from `POST /v1/oauth/token`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "403": { "description": "The access token is valid but does not carry the scope this operation requires.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "404": { "description": "No such resource, or the resource belongs to an organization your tenant does not own. These two cases are deliberately indistinguishable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "429": { "description": "Rate limit exceeded. Retry after the number of seconds given in the `Retry-After` header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } }, "500": { "description": "An unexpected error occurred on our side. The `requestId` in the response body identifies this failure in our logs.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetailsDto" } } } } }, "security": [ { "oauth2": [ "fleet:write" ] } ], "summary": "Remove a vehicle", "tags": [ "Vehicles" ] } } }, "info": { "title": "Crashwise Public API", "description": "The Crashwise Public API gives partner systems programmatic access to accident\ndocumentation: the reports themselves, the parties involved, the vehicles and\ndrivers they concern, and the files and analysis attached to them.\n\nIt is a JSON API over HTTPS. Every request is authenticated with an OAuth 2.0\nbearer token, every collection is paginated the same way, and every error uses\nthe same shape. If you have integrated with a REST API before, nothing here\nwill surprise you.\n\n> **Private beta.** Client credentials are issued manually to named integration\n> partners; there is no self-service signup, and every request without valid\n> credentials returns `401`. To request access, write to **dev@crashwise.app**\n> and describe the integration you have in mind.\n\n---\n\n## Getting started\n\n**1. Obtain client credentials.** We issue you a client identifier and a client\nsecret, scoped to your tenant.\n\n**2. Exchange them for an access token.**\n\n```bash\ncurl -X POST https://api.public.crashwise.app/v1/oauth/token \\\n -u \"$CRASHWISE_CLIENT_ID:$CRASHWISE_CLIENT_SECRET\" \\\n -d grant_type=client_credentials\n```\n\n```json\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"scope\": \"reports:read fleet:read fleet:write\"\n}\n```\n\n**3. Call the API.**\n\n```bash\ncurl https://api.public.crashwise.app/v1/reports?limit=10 \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"\n```\n\nThe base URL is `https://api.public.crashwise.app/v1`. There is no sandbox\nenvironment; integration work happens against production with credentials\nscoped to organizations you control.\n\n---\n\n## Authentication\n\nThe API uses the OAuth 2.0 **client credentials** grant ([RFC 6749][rfc6749]\nsection 4.4). Your integration authenticates as itself, not on behalf of an\ninteractively signed-in person, so there is no authorization-code flow, no\nredirect URI, and no refresh token.\n\nSend credentials with HTTP Basic authentication where you can — it keeps the\nsecret out of request bodies, which are more likely to end up in logs. Passing\n`client_id` and `client_secret` as form fields is also accepted.\n\nAccess tokens are valid for **one hour**. Cache the token for its lifetime and\nrequest a new one when it expires. The token endpoint is rate-limited more\nstrictly than the rest of the API; an integration that mints a fresh token for\nevery call will be throttled.\n\nTreat the client secret as you would a password. It must never appear in a\nmobile application, a browser bundle, a public repository, or any artifact you\ndistribute. If a secret is exposed, contact us and we will rotate it.\n\n### Scopes\n\nScopes are grouped by domain rather than by endpoint, so that least privilege\nis expressible without reasoning about forty separate strings. Request only\nwhat your integration needs.\n\n| Scope | Grants |\n|---|---|\n| `reports:read` | Read accident reports, their parties, messages and sketches |\n| `reports:write` | Create and modify accident reports, their parties, messages and sketches |\n| `fleet:read` | Read vehicles and vehicle reference data |\n| `fleet:write` | Create, modify and remove vehicles, including bulk import |\n| `users:read` | Read users and their driving licences |\n| `users:write` | Create, modify and remove users and their driving licences |\n| `organizations:read` | Read organizations owned by your tenant |\n| `organizations:write` | Create, modify and remove organizations owned by your tenant |\n| `files:read` | Read uploads, attachments and document metadata |\n| `files:write` | Upload files, run document analysis and manage attachments |\n\nReference and service-metadata endpoints — circumstance types, vehicle\nmanufacturers, insurance lookup and health — require a valid token but no\nparticular scope.\n\nOmitting the `scope` parameter grants every scope your client is entitled to,\nwhich is the right default for most integrations. Requesting a scope your\nclient does not hold returns `invalid_scope` rather than silently narrowing\nthe grant, so a misconfigured deployment fails loudly at startup instead of\nmysteriously 403-ing hours later.\n\n---\n\n## Tenancy and organizations\n\nYour credentials identify a **tenant**. A tenant owns one or more\n**organizations**, and an organization is the unit that owns vehicles, users\nand accident reports. A fleet operator managing several customer fleets models\neach as its own organization under a single tenant.\n\nBecause a tenant may own many organizations, `organizationId` is explicit\nrather than inferred. Write operations require it; list operations accept it as\na filter and, when omitted, return results across every organization your\ntenant owns.\n\nReferencing an organization your tenant does not own returns **`404 Not\nFound`**, not `403 Forbidden`. This is deliberate: a `403` would confirm\nthat the identifier exists, which would let a caller enumerate other tenants'\nresources. Every cross-tenant reference is indistinguishable from a\nnonexistent one.\n\n---\n\n## Acting on behalf of your users\n\nSome operations record who performed them — filing an accident report,\nuploading a photograph, signing a document. Client credentials carry no user\nidentity, so where an action has a human subject, the relevant endpoint takes\nan explicit user identifier (`userId`, or `createdByUserId` on creation).\n\nYour tenant asserts which of its own users an action belongs to, and we trust\nthat assertion. That trust is precisely why credentials are issued manually to\nnamed partners rather than through self-service signup. The user must belong to\nan organization your tenant owns; otherwise the request returns `404`,\nfollowing the rule above.\n\n---\n\n## Errors\n\nEvery error response except one uses [RFC 9457][rfc9457] problem details, served\nas `application/problem+json`:\n\n```json\n{\n \"type\": \"https://api.public.crashwise.app/docs/errors/insufficient-scope\",\n \"title\": \"Forbidden\",\n \"status\": 403,\n \"detail\": \"This operation requires the 'fleet:write' scope.\",\n \"instance\": \"/v1/vehicles\",\n \"requestId\": \"req_01JBQ7K3M9XN4P2VYD8ZFA6RTC\",\n \"code\": \"insufficient_scope\"\n}\n```\n\nBranch on `code`, not on `detail` — `detail` is written for humans and may\nbe reworded without notice. Log `requestId` on every failure; quoting it is by\nfar the fastest way for us to find the corresponding entry in our logs.\n\nThe exception is `POST /v1/oauth/token`, which returns the error shape\nmandated by [RFC 6749][rfc6749] section 5.2 (`error`,\n`error_description`, `error_uri`) so that standard OAuth client libraries\ncan parse it.\n\n| Status | Meaning |\n|---|---|\n| `400` | Malformed request — unparseable body, invalid query parameter |\n| `401` | Missing, expired or malformed access token |\n| `403` | Valid token, but it lacks the scope this operation requires |\n| `404` | No such resource, or it belongs to an organization your tenant does not own |\n| `409` | Conflict with the current state — for example a duplicate registration number |\n| `422` | Body parsed but failed validation; `errors` names each offending field |\n| `429` | Rate limit exceeded; see `Retry-After` |\n| `5xx` | A fault on our side. Retry with backoff and quote `requestId` if it persists |\n\nRetry `429` and `5xx` with exponential backoff. Do not retry `4xx`\nresponses other than `429` — they will fail identically until the request\nitself changes.\n\n---\n\n## Pagination\n\nCollection endpoints are paginated with `page` (1-based) and `limit`.\n`limit` defaults to 10 and caps at 100.\n\n```json\n{\n \"data\": [],\n \"meta\": {\n \"page\": 1,\n \"limit\": 10,\n \"totalItems\": 42,\n \"totalPages\": 5,\n \"hasNextPage\": true,\n \"hasPreviousPage\": false\n }\n}\n```\n\nDrive iteration from `meta.hasNextPage` rather than comparing counts\nyourself. When walking a large collection, sort by a stable field — records\ncreated while you paginate can otherwise shift rows between pages.\n\n---\n\n## Rate limits\n\nEvery response carries the current window's state:\n\n| Header | Meaning |\n|---|---|\n| `X-RateLimit-Limit` | Requests permitted in the current window |\n| `X-RateLimit-Remaining` | Requests remaining in the current window |\n| `X-RateLimit-Reset` | Unix timestamp, in seconds, when the window resets |\n\nExceeding the limit returns `429` with a `Retry-After` header giving the\nseconds to wait. Limits are applied per tenant, not per credential, so adding\nclient credentials does not raise your ceiling. If your integration needs a\nhigher limit, ask — bulk import endpoints in particular are usually a better\nanswer than a raised limit.\n\n---\n\n## Idempotency\n\nCreation and bulk-import endpoints accept an `Idempotency-Key` header: any\nunique string, a UUID being the obvious choice.\n\n```bash\ncurl -X POST https://api.public.crashwise.app/v1/vehicles \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\" \\\n -H \"Idempotency-Key: 9f8c1b2e-4a7d-4f31-9c5e-2b6a0d3f7e18\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"organizationId\": \"...\", \"registrationNumber\": \"ABC-1234\" }'\n```\n\nReplaying a request with a key we have already seen returns the original\nresponse instead of creating a second record. Keys are retained for 24 hours.\nUse this whenever a network timeout leaves you unsure whether a write landed —\nretrying with the same key is always safe.\n\n---\n\n## Versioning\n\nThe major version is in the path: `/v1`. Within a version we make only\nbackward-compatible changes — new endpoints, new optional request fields, new\nresponse fields.\n\nWrite your client to tolerate them: **ignore response fields you do not\nrecognise**, and do not depend on the ordering of object keys or of array\nelements that are not explicitly sorted. A client that rejects unknown fields\nwill break on a routine addition.\n\nBreaking changes ship as `/v2`. We will announce them ahead of time and\ncontinue to run `/v1` for an agreed migration period.\n\n[rfc6749]: https://datatracker.ietf.org/doc/html/rfc6749\n[rfc9457]: https://datatracker.ietf.org/doc/html/rfc9457", "version": "1.0.0", "contact": { "name": "Crashwise Integrations", "url": "https://api.public.crashwise.app/docs", "email": "dev@crashwise.app" }, "termsOfService": "https://crashwise.app/terms-and-conditions", "license": { "name": "Crashwise Public API Licence", "url": "https://crashwise.app/terms-and-conditions" } }, "tags": [ { "name": "OAuth", "description": "Exchange client credentials for an access token. Every other endpoint requires one." }, { "name": "Accident Reports", "description": "The central resource. A report documents a single road traffic accident: when and where it happened, the vehicles and people involved, the circumstances agreed between the parties, and the photographs, sketches and documents gathered at the scene. Reports move from an open, editable state through completion to signature; once signed, the record and its generated PDF are fixed." }, { "name": "Report Opponents", "description": "The other parties to an accident — their vehicle, insurer and contact details. Opponents are recorded per report and are not shared between reports, because the same registration plate may be insured differently on different dates. Invitations that let an opponent complete their own details are issued through the Crashwise applications and are not part of this API." }, { "name": "Report Witnesses", "description": "People who saw an accident but were not involved in it. Witness records exist to preserve contact details and a statement while they are still available at the scene." }, { "name": "Messages", "description": "The conversation attached to a report — questions, clarifications and notes exchanged while documentation is being assembled. Useful for surfacing outstanding queries in your own interface rather than requiring users to switch applications." }, { "name": "Sketch", "description": "The scene diagram: road layout, vehicle positions and directions of travel at the moment of impact. Stored as structured data rather than a flat image, so it can be re-rendered at any size and inspected programmatically." }, { "name": "Vehicles", "description": "The fleet. Vehicles carry identification (VIN, registration number, internal fleet number), technical specification, and the insurance details that are copied onto a report when the vehicle is involved in an accident. Bulk import is the right tool for an initial sync or a nightly reconciliation; the single-vehicle endpoints are for incremental changes." }, { "name": "Vehicle Manufacturers", "description": "Reference list of recognised manufacturers and their models, used to normalise vehicle records. Requires a valid token but no particular scope." }, { "name": "Users", "description": "The people in your organizations — drivers and administrators. A user is the subject of an accident report and the actor recorded against documentation activity. Bulk import mirrors the vehicle import for onboarding a fleet in one operation." }, { "name": "Driving Licences", "description": "Licence records held against a user, including category entitlements and expiry. Licence data can be captured by photographing the document; see Files for the scanning endpoints." }, { "name": "Organizations", "description": "The unit that owns vehicles, users and reports. A tenant may own many organizations — typically one per customer fleet — and every other resource in this API belongs to exactly one of them. Also carries notification settings and the recipients that completed reports are shared with." }, { "name": "Files", "description": "Upload and analysis of documents photographed at the scene. Beyond plain upload, these endpoints extract structured data from driving licences, insurance cards, vehicle registration certificates and licence plates, so an integration can populate a report from photographs rather than manual entry." }, { "name": "Uploads", "description": "Media captured during documentation — photographs, video and audio — together with storage accounting and, for audio, transcription status. Transcription is asynchronous: create the upload, then poll for the result." }, { "name": "Photo Validation", "description": "Checks that a photograph is usable as evidence before it is attached to a report: whether it is sharp enough, adequately lit, and actually shows what the step asked for. Running validation at capture time avoids discovering a useless photograph weeks later during a claim." }, { "name": "Crash Assistant", "description": "Guided documentation. The assistant walks a driver through what to capture at a scene, adapting to what has already been recorded, and produces the structured summary attached to a completed report. Useful if you want to embed the guided flow in your own application rather than sending users to ours." }, { "name": "Circumstance Types", "description": "Reference list of the standardised accident circumstances used on the European Accident Statement, such as manoeuvring, changing lanes, or reversing. Requires a valid token but no particular scope." }, { "name": "Insurance Lookup", "description": "Resolves an insurer from a policy or green-card identifier, so that opponent insurance details can be normalised rather than stored as free text. Requires a valid token but no particular scope." }, { "name": "Issue Reports", "description": "Report a problem with the service from inside your integration. Requires a valid token but no particular scope." }, { "name": "Health", "description": "Service liveness. Suitable as a connectivity check from your monitoring; it does not consume rate-limit budget in a way that would mask real traffic." } ], "servers": [ { "url": "https://api.public.crashwise.app/v1", "description": "Production" } ], "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.public.crashwise.app/v1/oauth/token", "scopes": { "reports:read": "Read accident reports, their parties, messages and sketches.", "reports:write": "Create and modify accident reports, their parties, messages and sketches.", "fleet:read": "Read vehicles and vehicle reference data.", "fleet:write": "Create, modify and remove vehicles, including bulk import.", "users:read": "Read users and their driving licences.", "users:write": "Create, modify and remove users and their driving licences.", "organizations:read": "Read organizations owned by your tenant.", "organizations:write": "Create, modify and remove organizations owned by your tenant.", "files:read": "Read uploads, attachments and document metadata.", "files:write": "Upload files, run document analysis and manage attachments." } } }, "description": "OAuth 2.0 client credentials. Obtain a token from `POST /v1/oauth/token` and send it as `Authorization: Bearer `." } }, "schemas": { "TokenRequestDto": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Must be `client_credentials`. This is the only grant type the Crashwise Public API supports; there is no authorization-code or refresh-token flow, because integrations act as themselves rather than on behalf of an interactively signed-in person.", "example": "client_credentials", "enum": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Your client identifier. May be supplied here or, preferably, via HTTP Basic authentication in the `Authorization` header.", "example": "cw_client_7f3a9c2e4b1d" }, "client_secret": { "type": "string", "description": "Your client secret. May be supplied here or, preferably, via HTTP Basic authentication in the `Authorization` header. Never embed this value in a mobile application, a browser bundle, or any other artifact you distribute.", "example": "cw_secret_9d4e7a2f8c6b1e5a3d0f" }, "scope": { "type": "string", "description": "Space-delimited list of scopes to request. Omit to receive every scope your client is entitled to. Requesting a scope your client does not hold returns `invalid_scope` rather than silently narrowing the grant.", "example": "reports:read fleet:read fleet:write" } }, "required": [ "grant_type" ] }, "TokenResponseDto": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The bearer token to present in the `Authorization` header of subsequent requests.", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIwMjYtMDgifQ.eyJpc3MiOiJodHRwczovL2FwaS5wdWJsaWMuY3Jhc2h3aXNlLmFwcCJ9.signature" }, "token_type": { "type": "string", "description": "Always `Bearer`.", "example": "Bearer", "enum": [ "Bearer" ] }, "expires_in": { "type": "number", "description": "Lifetime of the access token in seconds. Tokens are short-lived; request a new one rather than caching beyond this window.", "example": 3600 }, "scope": { "type": "string", "description": "Space-delimited list of scopes actually granted, which may be narrower than requested.", "example": "reports:read fleet:read fleet:write" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "OAuthErrorDto": { "type": "object", "properties": { "error": { "type": "string", "description": "A single ASCII error code from RFC 6749 section 5.2.", "example": "invalid_client", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope" ] }, "error_description": { "type": "string", "description": "Human-readable text providing additional information about the error.", "example": "Client authentication failed." }, "error_uri": { "type": "string", "description": "A URI identifying a human-readable web page with information about the error.", "example": "https://api.public.crashwise.app/docs/errors/invalid-client" } }, "required": [ "error", "error_description" ] }, "ProblemDetailsDto": { "type": "object", "properties": { "type": { "type": "string", "description": "A URI identifying the problem type. Dereference it for a human-readable explanation of this class of error.", "example": "https://api.public.crashwise.app/docs/errors/unauthorized" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type.", "example": "Unauthorized" }, "status": { "type": "number", "description": "The HTTP status code for this occurrence of the problem.", "example": 401 }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem.", "example": "The access token is missing, expired, or does not grant the required scope." }, "instance": { "type": "string", "description": "The path of the request that produced this problem.", "example": "/v1/reports" }, "requestId": { "type": "string", "description": "A unique identifier for this request. Quote it when contacting support — it is the fastest way for us to find the corresponding log entry.", "example": "req_01JBQ7K3M9XN4P2VYD8ZFA6RTC" }, "code": { "type": "string", "description": "A stable, machine-readable error code. Use this rather than parsing `detail`, which may be reworded.", "example": "insufficient_scope" } }, "required": [ "type", "title", "status", "detail", "instance", "requestId" ] }, "CreateReportDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The UUID of the organization", "example": "550e8400-e29b-41d4-a716-446655440001" }, "userId": { "type": "string", "description": "The UUID of the reporting user", "example": "550e8400-e29b-41d4-a716-446655440002" }, "organizationVehicleId": { "type": "string", "description": "UUID of vehicle A (organization vehicle)", "example": "550e8400-e29b-41d4-a716-446655440003" }, "isAnotherVehicleInvolved": { "type": "boolean", "description": "Whether another vehicle is involved in the accident", "example": true }, "otherVehicleVin": { "type": "string", "description": "Other vehicle VIN (only when isAnotherVehicleInvolved is true)", "example": "5FNRL5H63DB123456" }, "otherVehicleManufacturer": { "type": "string", "description": "Other vehicle manufacturer (only when isAnotherVehicleInvolved is true)", "example": "Honda" }, "otherVehicleModel": { "type": "string", "description": "Other vehicle model (only when isAnotherVehicleInvolved is true)", "example": "Civic" }, "otherVehicleType": { "type": "string", "description": "Other vehicle type (only when isAnotherVehicleInvolved is true)", "example": "Sedan" }, "otherVehicleRegistrationNumber": { "type": "string", "description": "Other vehicle registration number (only when isAnotherVehicleInvolved is true)", "example": "XYZ-5678" }, "otherVehicleColor": { "type": "string", "description": "Other vehicle color (only when isAnotherVehicleInvolved is true)", "example": "Red" }, "otherVehicleDisplacementCCM": { "type": "number", "description": "Other vehicle displacement CCM (only when isAnotherVehicleInvolved is true)", "example": 1998 }, "otherVehicleFuelType": { "type": "string", "description": "Other vehicle fuel type (only when isAnotherVehicleInvolved is true)", "example": "Petrol" }, "otherVehicleMassInService": { "type": "number", "description": "Other vehicle mass in service (only when isAnotherVehicleInvolved is true)", "example": 1500 }, "otherVehicleMaxMass": { "type": "number", "description": "Other vehicle max mass (only when isAnotherVehicleInvolved is true)", "example": 2000 }, "otherVehiclePowerKW": { "type": "number", "description": "Other vehicle power kW (only when isAnotherVehicleInvolved is true)", "example": 110 }, "otherVehicleSeatsNumber": { "type": "number", "description": "Other vehicle seats number (only when isAnotherVehicleInvolved is true)", "example": 5 }, "otherVehicleInsuranceCompany": { "type": "string", "description": "Other vehicle insurance company (only when isAnotherVehicleInvolved is true)", "example": "State Farm" }, "otherVehicleInsurancePolicyNumber": { "type": "string", "description": "Other vehicle insurance policy number (only when isAnotherVehicleInvolved is true)", "example": "POL-789012" }, "otherVehicleInsuranceCompany2": { "type": "string", "description": "Other vehicle secondary insurance company (only when isAnotherVehicleInvolved is true)", "example": "Allstate" }, "otherVehicleInsurancePolicyNumber2": { "type": "string", "description": "Other vehicle secondary insurance policy number (only when isAnotherVehicleInvolved is true)", "example": "POL-345678" }, "otherVehicleOwnerFirstName": { "type": "string", "description": "Other vehicle owner first name (only when isAnotherVehicleInvolved is true)", "example": "Jane" }, "otherVehicleOwnerLastName": { "type": "string", "description": "Other vehicle owner last name (only when isAnotherVehicleInvolved is true)", "example": "Smith" }, "otherVehicleOwnerPhone": { "type": "string", "description": "Other vehicle owner phone (only when isAnotherVehicleInvolved is true)", "example": "+1234567890" }, "otherVehicleOwnerEmail": { "type": "string", "description": "Other vehicle owner email (only when isAnotherVehicleInvolved is true)", "example": "jane@example.com" }, "otherVehicleOwnerAddress": { "type": "string", "description": "Other vehicle owner address (only when isAnotherVehicleInvolved is true)", "example": "456 Oak St" }, "otherVehicleInsuredIsCompany": { "type": "boolean", "description": "Whether the other vehicle owner is a company (only when isAnotherVehicleInvolved is true)", "example": false }, "otherVehicleInsuredCompanyName": { "type": "string", "description": "Other vehicle company name if owner is a company (only when isAnotherVehicleInvolved is true)", "example": "ABC Company Ltd" }, "otherVehicleInitialPointOfImpact": { "type": "string", "description": "Other vehicle point of impact (only when isAnotherVehicleInvolved is true)", "example": "Rear bumper" }, "otherVehicleSecondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones on the other vehicle besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "otherVehicleVisibleDamage": { "type": "string", "description": "Other vehicle visible damage (only when isAnotherVehicleInvolved is true)", "example": "Rear bumper damaged" }, "otherDriverLanguage": { "type": "string", "description": "Other vehicle language (only when isAnotherVehicleInvolved is true)", "example": "English" }, "otherDriverFirstName": { "type": "string", "description": "Other vehicle driver first name (only when isAnotherVehicleInvolved is true)", "example": "Jane" }, "otherDriverLastName": { "type": "string", "description": "Other vehicle driver last name (only when isAnotherVehicleInvolved is true)", "example": "Smith" }, "otherDriverAddress": { "type": "string", "description": "Other vehicle driver address (only when isAnotherVehicleInvolved is true)", "example": "456 Oak St, Los Angeles, CA 90001" }, "otherDriverEmail": { "type": "string", "description": "Other vehicle driver personal email (only when isAnotherVehicleInvolved is true)", "example": "other.driver@example.com" }, "otherDriverPhone": { "type": "string", "description": "Other vehicle driver personal phone (only when isAnotherVehicleInvolved is true)", "example": "+1 555 987 6543" }, "otherDriverZipCode": { "type": "string", "description": "Other vehicle driver zip code (only when isAnotherVehicleInvolved is true)", "example": "90001" }, "otherDriverCity": { "type": "string", "description": "Other vehicle driver city (only when isAnotherVehicleInvolved is true)", "example": "Los Angeles" }, "otherDriverCountry": { "type": "string", "description": "Other vehicle driver country (only when isAnotherVehicleInvolved is true)", "example": "United States" }, "otherDriverLicenceNumber": { "type": "string", "description": "Other vehicle driver licence number (only when isAnotherVehicleInvolved is true)", "example": "DL789012" }, "otherDriverLicenceGroups": { "type": "array", "description": "Other vehicle driver licence groups (only when isAnotherVehicleInvolved is true) - can be array or comma-separated string", "example": [ "B", "BE" ], "items": { "type": "string" } }, "otherDriverLicenceIssuedBy": { "type": "string", "description": "Other vehicle driver licence issued by (only when isAnotherVehicleInvolved is true)", "example": "DMV California" }, "otherDriverLicenceValidFrom": { "type": "string", "description": "Other vehicle driver licence valid from (only when isAnotherVehicleInvolved is true)", "example": "2019-06-01" }, "otherDriverLicenceValidTo": { "type": "string", "description": "Other vehicle driver licence valid to (only when isAnotherVehicleInvolved is true)", "example": "2029-06-01" }, "otherDriverDob": { "type": "string", "description": "Other vehicle driver date of birth (only when isAnotherVehicleInvolved is true)", "example": "1985-03-20" }, "otherDriverSignature": { "type": "string", "description": "Other vehicle driver signature (only when isAnotherVehicleInvolved is true)", "example": "data:image/png;base64,..." }, "dateAndTime": { "type": "string", "description": "Date and time of the accident in user's local timezone (e.g., \"2024-01-15T14:30:00\"). The backend will convert this to UTC using timezoneOffsetHours.", "example": "2024-01-15T14:30:00" }, "location": { "type": "string", "description": "Location of the accident", "example": "Main Street and 5th Avenue" }, "locationLat": { "type": "number", "description": "Latitude", "example": 40.7128 }, "locationLng": { "type": "number", "description": "Longitude", "example": -74.006 }, "locationCountry": { "type": "string", "description": "Country where accident occurred", "example": "United States" }, "driverFirstName": { "type": "string", "description": "Driver first name", "example": "John" }, "driverLastName": { "type": "string", "description": "Driver last name", "example": "Doe" }, "driverAddress": { "type": "string", "description": "Driver address", "example": "123 Main St" }, "driverEmail": { "type": "string", "description": "Driver personal email", "example": "driver@example.com" }, "driverPhone": { "type": "string", "description": "Driver personal phone", "example": "+1 555 123 4567" }, "driverZipCode": { "type": "string", "description": "Driver zip code", "example": "10001" }, "driverCity": { "type": "string", "description": "Driver city", "example": "New York" }, "driverCountry": { "type": "string", "description": "Driver country", "example": "United States" }, "driverLicenceNumber": { "type": "string", "description": "Driver licence number", "example": "DL123456" }, "driverLicenceGroups": { "type": "array", "description": "Driver licence groups (can be array or comma-separated string)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "driverLicenceIssuedBy": { "type": "string", "description": "Driver licence issued by", "example": "DMV New York" }, "driverLicenceValidFrom": { "type": "string", "description": "Driver licence valid from", "example": "2020-01-01" }, "driverLicenceValidTo": { "type": "string", "description": "Driver licence valid to", "example": "2030-01-01" }, "driverSignature": { "type": "string", "description": "Driver signature", "example": "data:image/png;base64,..." }, "driverOccupation": { "type": "string", "description": "Driver occupation", "example": "Engineer" }, "driverDob": { "type": "string", "description": "Driver date of birth", "example": "1990-05-15" }, "driverTheoryTestPassed": { "type": "boolean", "description": "Driver theory test passed", "example": true }, "driverDrivingWithPermission": { "type": "boolean", "description": "Driver driving with permission", "example": true }, "driverIsEmployee": { "type": "boolean", "description": "Driver is employee", "example": true }, "driverHasDisabilities": { "type": "boolean", "description": "Driver has disabilities", "example": false }, "hasInjuries": { "type": "boolean", "description": "Has injuries", "example": false }, "injuriesDescription": { "type": "string", "description": "Injuries description", "example": "Minor cuts" }, "hasPropertyDamage": { "type": "boolean", "description": "Has property damage", "example": true }, "propertyDamageDescription": { "type": "string", "description": "Property damage description", "example": "Front bumper damaged" }, "accidentDescription": { "type": "string", "description": "Accident description", "example": "Vehicle A was proceeding..." }, "accidentPlan": { "type": "string", "description": "Accident plan/diagram", "example": "data:image/png;base64,..." }, "initialPointOfImpact": { "type": "string", "description": "Point of initial impact on vehicle A", "example": "Front left" }, "secondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones on vehicle A besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "reportedToPolice": { "type": "boolean", "description": "Reported to police", "example": true }, "policeConstableName": { "type": "string", "description": "Police constable name", "example": "Officer Smith" }, "policeConstableBadgeNumber": { "type": "string", "description": "Police constable badge number", "example": "12345" }, "policeConstableTime": { "type": "string", "description": "Police constable time", "example": "14:45" }, "warningOfProsecution": { "type": "boolean", "description": "Warning of prosecution", "example": false }, "prosecutionAgainst": { "type": "string", "description": "Prosecution against", "example": "Driver B" }, "weatherConditions": { "type": "string", "description": "Weather conditions", "example": "Clear" }, "weatherAirTemperature": { "type": "number", "description": "Weather air temperature in Celsius", "example": 22.5 }, "weatherPrecipitationAmount": { "type": "number", "description": "Weather precipitation amount", "example": 0 }, "weatherSymbolCode": { "type": "string", "description": "Weather symbol code", "example": "01d" }, "weatherWindSpeed": { "type": "number", "description": "Weather wind speed in km/h", "example": 15.5 }, "weatherVisibility": { "type": "number", "description": "Visibility in meters", "example": 10000 }, "weatherRoadConditions": { "type": "string", "description": "Road surface conditions", "example": "Dry" }, "weatherPrecipitation": { "type": "string", "description": "Precipitation type", "example": "None" }, "weatherHumidity": { "type": "number", "description": "Humidity percentage", "example": 65 }, "speedVehicleA": { "type": "string", "description": "Speed of vehicle A", "example": "50 km/h" }, "speedVehicleB": { "type": "string", "description": "Speed of vehicle B", "example": "60 km/h" }, "warningsGiven": { "type": "string", "description": "Warnings given", "example": "Stop sign visible" }, "streetLightsIlluminated": { "type": "boolean", "description": "Street lights illuminated", "example": false }, "lightsDisplayed": { "type": "string", "description": "Lights displayed", "example": "Headlights on" }, "vehicleLoadWeight": { "type": "string", "description": "Vehicle load weight", "example": "500kg" }, "obstacle": { "type": "string", "description": "Obstacle description", "example": "Street sign" }, "visibleDamage": { "type": "string", "description": "Visible damage on vehicle A", "example": "Front bumper" }, "isDamageInsured": { "type": "boolean", "description": "Is damage insured on vehicle A", "example": true }, "insuredVehicleStillInUse": { "type": "boolean", "description": "Insured vehicle still in use", "example": false }, "drivabilityVerdict": { "type": "string", "description": "Outcome of the guided drivability check (CW-1357)", "example": "not_roadworthy", "enum": [ "not_roadworthy", "restricted", "roadworthy" ] }, "drivabilityFindings": { "type": "array", "description": "Findings behind the drivability verdict", "example": [ "lighting_failure", "fluid_leak_or_smoke" ], "items": { "type": "string" } }, "drivabilityCheckCompleted": { "type": "boolean", "description": "True when the driver worked through the guided check rather than only answering Yes/No", "example": true }, "insuredVehiclePresentLocation": { "type": "string", "description": "Insured vehicle present location", "example": "Repair shop on 10th Street" }, "insuredVehicleCarryingCapacity": { "type": "string", "description": "Insured vehicle carrying capacity", "example": "5 passengers" }, "insuredVehicleFirstRegistration": { "type": "string", "description": "Insured vehicle first registration date", "example": "2018-03-15" }, "insuredVehicleOwnedByUser": { "type": "boolean", "description": "Insured vehicle owned by user", "example": true }, "insuredVehicleOwnerName": { "type": "string", "description": "Insured vehicle owner name if not user", "example": "ABC Leasing Company" }, "insuredVehicleOwnerAddress": { "type": "string", "description": "Insured vehicle owner address", "example": "789 Business Park" }, "insuredVehicleOwnerPhone": { "type": "string", "description": "Insured vehicle owner phone", "example": "+43 1 5550000" }, "insuredVehiclePreviousDamage": { "type": "string", "description": "Insured vehicle previous damage", "example": "Minor scratch on rear door" }, "insuredVehicleFinanceCompany": { "type": "string", "description": "Insured vehicle finance company", "example": "Auto Finance Corp" }, "insuredParentSpousePhone": { "type": "string", "description": "Insured parent or spouse phone", "example": "+1234567890" }, "signatureDocumentId": { "type": "string", "description": "Digital signer document ID", "example": "DOC-123456" }, "signatureRequestCompleted": { "type": "boolean", "description": "Digital signer signature request completed", "example": true }, "signatureRequestId": { "type": "string", "description": "Digital signer signature request ID", "example": "REQ-789012" }, "signatureUrl": { "type": "string", "description": "Digital signer sign URL", "example": "https://signing.crashwise.app/s/abc123" }, "accidentReportStatusId": { "type": "string", "description": "Accident report status ID", "example": "STATUS-001" }, "timezoneOffsetHours": { "type": "number", "description": "Timezone offset in hours from UTC (e.g., GMT+3 = 3, GMT-5 = -5). **STRONGLY RECOMMENDED** to correctly store and display accident time in PDFs and UI. Without this field, times will be displayed in UTC instead of user's local time. the mobile application should calculate and send device timezone offset using: `new Date().getTimezoneOffset() / -60` (note the negative sign!). Example: If user is in GMT+3, send 3. If user is in GMT-5, send -5.", "example": 3 }, "dateSignedOffsetHours": { "type": "string", "description": "Date signed with offset hours", "example": "2024-01-15T14:30:00.000Z" }, "remarks": { "type": "string", "description": "Remarks", "example": "Additional notes" }, "circumstancesVehicleA": { "type": "array", "description": "Circumstances for Vehicle A (snake_case values)", "example": [ "reversing", "turning_left" ], "items": { "type": "string" } }, "circumstancesVehicleB": { "type": "array", "description": "Circumstances for Vehicle B (snake_case values)", "example": [ "parked" ], "items": { "type": "string" } } }, "required": [ "organizationId", "userId", "organizationVehicleId", "dateAndTime", "location", "driverFirstName", "driverLastName" ] }, "OrganizationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the organization", "example": "550e8400-e29b-41d4-a716-446655440000" }, "code": { "type": "string", "description": "Unique 8-character uppercase code for the organization", "example": "CRASHWIS" }, "name": { "type": "string", "description": "The name of the organization", "example": "Crashwise Inc." }, "normalizedName": { "type": "string", "description": "Normalized name (uppercase, no special characters) for search", "example": "CRASHWISE INC" }, "defaultLanguage": { "type": "string", "description": "Default language for the organization", "example": "English" }, "defaultLanguageCode": { "type": "string", "description": "Default language code (ISO 639-1)", "example": "en" }, "address": { "type": "object", "description": "Address of the organization", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "additionalProperties": true }, "driversHaveAccessToAllVehicles": { "type": "boolean", "description": "Whether drivers have access to all vehicles or only assigned ones", "example": true }, "newReportNotificationEnabled": { "type": "boolean", "description": "Whether to email a notification when a new accident report is created", "example": false }, "newReportNotificationEmail": { "type": "string", "description": "Address that receives the new-accident-report notification email", "example": "ops@acme.com" }, "insuranceEmail": { "type": "string", "description": "Insurance address offered as a recipient when sharing a report (CW-1389)", "example": "claims@insurer.com" }, "repairShopEmail": { "type": "string", "description": "Repair shop address offered as a recipient when sharing a report (CW-1389)", "example": "service@workshop.com" }, "createdAt": { "type": "string", "description": "The date when the organization was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date when the organization was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deletedAt": { "type": "string", "description": "The date when the organization was deleted (soft delete)", "example": null, "format": "date-time" } }, "required": [ "id", "code", "name", "normalizedName", "defaultLanguage", "defaultLanguageCode", "address", "driversHaveAccessToAllVehicles", "newReportNotificationEnabled", "createdAt", "updatedAt" ] }, "UserLoginDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the user login", "example": "550e8400-e29b-41d4-a716-446655440000" }, "loginProvider": { "type": "string", "description": "The login provider name (e.g., Google, Facebook, Microsoft)", "example": "Google" }, "providerKey": { "type": "string", "description": "The unique key provided by the authentication provider", "example": "1234567890" }, "providerDisplayName": { "type": "string", "description": "Display name from the provider", "example": "John Doe" }, "userId": { "type": "string", "description": "The UUID of the user who owns this login", "example": "550e8400-e29b-41d4-a716-446655440001" }, "user": { "description": "The user who owns this login", "allOf": [ { "$ref": "#/components/schemas/UserDto" } ] }, "createdAt": { "type": "string", "description": "The date when the login was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date when the login was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" } }, "required": [ "id", "loginProvider", "providerKey", "userId", "user", "createdAt", "updatedAt" ] }, "UserDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the user", "example": "550e8400-e29b-41d4-a716-446655440000" }, "username": { "type": "string", "description": "The username of the user", "example": "john_doe" }, "email": { "type": "string", "description": "The email address of the user", "example": "john.doe@example.com" }, "isVerified": { "type": "boolean", "description": "Whether the email is verified", "example": true }, "phoneNumber": { "type": "string", "description": "The phone number of the user", "example": "+1234567890" }, "isPhoneNumberVerified": { "type": "boolean", "description": "Whether the phone number is verified", "example": false }, "is2FAEnabled": { "type": "boolean", "description": "Whether 2FA is enabled for the user", "example": false }, "accessFailedCount": { "type": "number", "description": "The number of failed access attempts", "example": 0 }, "firstName": { "type": "string", "description": "The first name of the user", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the user", "example": "Doe" }, "country": { "type": "string", "description": "The country of the user", "example": "United States" }, "timezone": { "type": "string", "description": "The timezone of the user", "example": "America/New_York" }, "address": { "type": "object", "description": "The address of the user", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "additionalProperties": true }, "defaultVehicleId": { "type": "string", "description": "The default vehicle ID for the user", "example": "550e8400-e29b-41d4-a716-446655440001" }, "organizationId": { "type": "string", "description": "The UUID of the organization this user belongs to", "example": "550e8400-e29b-41d4-a716-446655440002" }, "organization": { "description": "The organization this user belongs to", "allOf": [ { "$ref": "#/components/schemas/OrganizationDto" } ] }, "role": { "type": "string", "description": "The role of the user", "example": "driver", "enum": [ "driver", "admin", "group-admin", "super-admin" ] }, "languageCode": { "type": "string", "description": "Language code", "example": "English" }, "isSingleUse": { "type": "boolean", "description": "Whether this is an ephemeral single-use account created for a non-fixed driver via a QR/number-plate scan. Such users can record exactly one report.", "example": false }, "singleUseVehicleId": { "type": "string", "description": "For single-use accounts, the vehicle this account is locked to.", "example": "550e8400-e29b-41d4-a716-446655440001" }, "contactEmail": { "type": "string", "description": "The email address a single-use (QR/plate) driver entered for themselves. Kept apart from `email`, which stays a synthetic non-routable address for such accounts so a typed address can never collide with a real account or turn an access-less account into a sign-in-able one.", "example": "john.doe@example.com" }, "mergedIntoUserId": { "type": "string", "description": "Set on a single-use account whose contact data belongs to somebody who already has a real account in the same organization. The ephemeral row still backs the running session but is not a second person, so it is hidden from user management.", "example": "550e8400-e29b-41d4-a716-446655440003" }, "createdAt": { "type": "string", "description": "The date when the user was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date when the user was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deletedAt": { "type": "string", "description": "The date when the user was deleted (soft delete)", "example": null, "format": "date-time" }, "userLogins": { "description": "External login providers associated with this user", "type": "array", "items": { "$ref": "#/components/schemas/UserLoginDto" } } }, "required": [ "id", "username", "email", "isVerified", "isPhoneNumberVerified", "is2FAEnabled", "accessFailedCount", "firstName", "lastName", "role", "isSingleUse", "createdAt", "updatedAt" ] }, "VehicleDto": { "type": "object", "properties": {} }, "ReportDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the report", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "The UUID of the organization", "example": "550e8400-e29b-41d4-a716-446655440001" }, "organization": { "description": "The organization", "allOf": [ { "$ref": "#/components/schemas/OrganizationDto" } ] }, "userId": { "type": "string", "description": "The UUID of the reporting user", "example": "550e8400-e29b-41d4-a716-446655440002" }, "user": { "description": "The reporting user", "allOf": [ { "$ref": "#/components/schemas/UserDto" } ] }, "organizationVehicleId": { "type": "string", "description": "UUID of vehicle A (organization vehicle)", "example": "550e8400-e29b-41d4-a716-446655440003" }, "organizationVehicle": { "description": "Vehicle A (organization vehicle)", "allOf": [ { "$ref": "#/components/schemas/VehicleDto" } ] }, "isAnotherVehicleInvolved": { "type": "boolean", "description": "Whether another vehicle is involved in the accident", "example": true }, "otherVehicleVin": { "type": "string", "description": "Other vehicle VIN", "example": "5FNRL5H63DB123456" }, "otherVehicleManufacturer": { "type": "string", "description": "Other vehicle manufacturer/make", "example": "Honda" }, "otherVehicleModel": { "type": "string", "description": "Other vehicle model", "example": "Civic" }, "otherVehicleType": { "type": "string", "description": "Other vehicle type", "example": "Sedan" }, "otherVehicleRegistrationNumber": { "type": "string", "description": "Other vehicle registration/license plate", "example": "XYZ-5678" }, "otherVehicleColor": { "type": "string", "description": "Other vehicle color", "example": "Red" }, "otherVehicleDisplacementCCM": { "type": "number", "description": "Other vehicle displacement in CCM", "example": 1998 }, "otherVehicleFuelType": { "type": "string", "description": "Other vehicle fuel type", "example": "Petrol" }, "otherVehicleMassInService": { "type": "number", "description": "Other vehicle mass in service (kg)", "example": 1500 }, "otherVehicleMaxMass": { "type": "number", "description": "Other vehicle maximum mass (kg)", "example": 2000 }, "otherVehiclePowerKW": { "type": "number", "description": "Other vehicle power in kW", "example": 110 }, "otherVehicleSeatsNumber": { "type": "number", "description": "Other vehicle number of seats", "example": 5 }, "otherVehicleInsuranceCompany": { "type": "string", "description": "Other vehicle insurance company", "example": "State Farm" }, "otherVehicleInsurancePolicyNumber": { "type": "string", "description": "Other vehicle insurance policy number", "example": "POL-789012" }, "otherVehicleInsuranceCompany2": { "type": "string", "description": "Other vehicle secondary insurance company", "example": "Allstate" }, "otherVehicleInsurancePolicyNumber2": { "type": "string", "description": "Other vehicle secondary insurance policy number", "example": "POL-345678" }, "otherVehicleOwnerFirstName": { "type": "string", "description": "Other vehicle owner first name", "example": "Jane" }, "otherVehicleOwnerLastName": { "type": "string", "description": "Other vehicle owner last name", "example": "Smith" }, "otherVehicleOwnerPhone": { "type": "string", "description": "Other vehicle owner phone", "example": "+1234567890" }, "otherVehicleOwnerEmail": { "type": "string", "description": "Other vehicle owner email", "example": "jane.smith@example.com" }, "otherVehicleOwnerAddress": { "type": "string", "description": "Other vehicle owner address", "example": "456 Oak St, Los Angeles, CA 90001" }, "otherVehicleInsuredIsCompany": { "type": "boolean", "description": "Whether the other vehicle owner is a company", "example": false }, "otherVehicleInsuredCompanyName": { "type": "string", "description": "Other vehicle company name (if owner is a company)", "example": "ABC Company Ltd" }, "otherVehicleInitialPointOfImpact": { "type": "string", "description": "Other vehicle point of initial impact", "example": "Rear bumper" }, "otherVehicleSecondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones on the other vehicle besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "otherVehicleVisibleDamage": { "type": "string", "description": "Other vehicle visible damage", "example": "Rear bumper, tail lights" }, "otherDriverLanguage": { "type": "string", "description": "Other vehicle language", "example": "English" }, "otherDriverFirstName": { "type": "string", "description": "Other vehicle driver first name", "example": "Jane" }, "otherDriverLastName": { "type": "string", "description": "Other vehicle driver last name", "example": "Smith" }, "otherDriverAddress": { "type": "string", "description": "Other vehicle driver address", "example": "456 Oak St, Los Angeles, CA 90001" }, "otherDriverEmail": { "type": "string", "description": "Other vehicle driver personal email", "example": "other.driver@example.com" }, "otherDriverPhone": { "type": "string", "description": "Other vehicle driver personal phone", "example": "+1 555 987 6543" }, "otherDriverZipCode": { "type": "string", "description": "Other vehicle driver zip code", "example": "90001" }, "otherDriverCity": { "type": "string", "description": "Other vehicle driver city", "example": "Los Angeles" }, "otherDriverCountry": { "type": "string", "description": "Other vehicle driver country", "example": "United States" }, "otherDriverLicenceNumber": { "type": "string", "description": "Other vehicle driver licence number", "example": "DL789012" }, "otherDriverLicenceGroups": { "type": "array", "description": "Other vehicle driver licence groups", "example": [ "B", "BE" ], "items": { "type": "string" } }, "otherDriverLicenceIssuedBy": { "type": "string", "description": "Other vehicle driver licence issued by", "example": "DMV California" }, "otherDriverLicenceValidFrom": { "type": "string", "description": "Other vehicle driver licence valid from", "example": "2019-06-01", "format": "date-time" }, "otherDriverLicenceValidTo": { "type": "string", "description": "Other vehicle driver licence valid to", "example": "2029-06-01", "format": "date-time" }, "otherDriverDob": { "type": "string", "description": "Other vehicle driver date of birth", "example": "1985-03-20" }, "otherDriverSignature": { "type": "string", "description": "Other vehicle driver signature", "example": "data:image/png;base64,..." }, "dateAndTime": { "type": "string", "description": "Date and time of the accident (stored in UTC). When creating/updating, send user's local time along with timezoneOffsetHours. The backend converts to UTC for storage.", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "location": { "type": "string", "description": "Location of the accident", "example": "Main Street and 5th Avenue" }, "locationLat": { "type": "number", "description": "Latitude coordinate", "example": 40.7128 }, "locationLng": { "type": "number", "description": "Longitude coordinate", "example": -74.006 }, "locationCountry": { "type": "string", "description": "Country where accident occurred", "example": "United States" }, "driverFirstName": { "type": "string", "description": "Driver first name (Vehicle A)", "example": "John" }, "driverLastName": { "type": "string", "description": "Driver last name (Vehicle A)", "example": "Doe" }, "driverAddress": { "type": "string", "description": "Driver address (Vehicle A)", "example": "123 Main St, New York, NY 10001" }, "driverEmail": { "type": "string", "description": "Driver personal email (Vehicle A)", "example": "driver@example.com" }, "driverPhone": { "type": "string", "description": "Driver personal phone (Vehicle A)", "example": "+1 555 123 4567" }, "driverZipCode": { "type": "string", "description": "Driver zip code (Vehicle A)", "example": "10001" }, "driverCity": { "type": "string", "description": "Driver city (Vehicle A)", "example": "New York" }, "driverCountry": { "type": "string", "description": "Driver country (Vehicle A)", "example": "United States" }, "driverLicenceNumber": { "type": "string", "description": "Driver licence number (Vehicle A)", "example": "DL123456" }, "driverLicenceGroups": { "type": "array", "description": "Driver licence groups (Vehicle A)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "driverLicenceIssuedBy": { "type": "string", "description": "Driver licence issued by (Vehicle A)", "example": "DMV New York" }, "driverLicenceValidFrom": { "type": "string", "description": "Driver licence valid from (Vehicle A)", "example": "2020-01-01", "format": "date-time" }, "driverLicenceValidTo": { "type": "string", "description": "Driver licence valid to (Vehicle A)", "example": "2030-01-01", "format": "date-time" }, "driverSignature": { "type": "string", "description": "Driver signature (Vehicle A)", "example": "data:image/png;base64,..." }, "driverOccupation": { "type": "string", "description": "Driver occupation (Vehicle A)", "example": "Engineer" }, "driverDob": { "type": "string", "description": "Driver date of birth (Vehicle A)", "example": "1990-05-15" }, "driverTheoryTestPassed": { "type": "boolean", "description": "Driver theory test passed (Vehicle A)", "example": true }, "driverDrivingWithPermission": { "type": "boolean", "description": "Driver driving with permission (Vehicle A)", "example": true }, "driverIsEmployee": { "type": "boolean", "description": "Driver is employee (Vehicle A)", "example": true }, "driverHasDisabilities": { "type": "boolean", "description": "Driver has disabilities (Vehicle A)", "example": false }, "circumstancesVehicleA": { "type": "array", "description": "Circumstances for Vehicle A (snake_case values)", "example": [ "reversing", "turning_left" ], "items": { "type": "string" } }, "circumstancesVehicleB": { "type": "array", "description": "Circumstances for Vehicle B (snake_case values)", "example": [ "parked" ], "items": { "type": "string" } }, "hasInjuries": { "type": "boolean", "description": "Has injuries", "example": false }, "injuriesDescription": { "type": "string", "description": "Injuries description", "example": "Minor cuts and bruises" }, "hasPropertyDamage": { "type": "boolean", "description": "Has property damage", "example": true }, "propertyDamageDescription": { "type": "string", "description": "Property damage description", "example": "Front bumper damaged" }, "accidentPlan": { "type": "string", "description": "Accident plan/diagram", "example": "data:image/png;base64,..." }, "accidentDescription": { "type": "string", "description": "Detailed accident description", "example": "Vehicle A was proceeding through intersection when..." }, "initialPointOfImpact": { "type": "string", "description": "Point of initial impact on vehicle A", "example": "Front left" }, "secondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones on vehicle A besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "visibleDamage": { "type": "string", "description": "Visible damage on vehicle A", "example": "Front bumper, left headlight" }, "isDamageInsured": { "type": "boolean", "description": "Is damage insured on vehicle A", "example": true }, "insuredVehicleStillInUse": { "type": "boolean", "description": "Vehicle still in use", "example": false }, "drivabilityVerdict": { "type": "string", "description": "Outcome of the guided drivability check (CW-1357). `restricted` means the vehicle may only be moved under the condition named by the finding.", "example": "not_roadworthy", "enum": [ "not_roadworthy", "restricted", "roadworthy" ] }, "drivabilityFindings": { "type": "array", "description": "Findings behind the verdict. `user_reported` means the driver answered \"not drivable\" without working through the check.", "example": [ "lighting_failure", "fluid_leak_or_smoke" ], "items": { "type": "string" } }, "drivabilityCheckCompleted": { "type": "boolean", "description": "True when the driver worked through the guided check. Distinguishes \"checked, no defects found\" from a bare \"yes, it is drivable\".", "example": true }, "insuredVehiclePresentLocation": { "type": "string", "description": "Vehicle present location", "example": "Repair shop on 10th Street" }, "insuredVehicleCarryingCapacity": { "type": "string", "description": "Vehicle carrying capacity", "example": "5 passengers" }, "insuredVehicleFirstRegistration": { "type": "string", "description": "Vehicle first registration date", "example": "2018-03-15", "format": "date-time" }, "insuredVehicleOwnedByUser": { "type": "boolean", "description": "Vehicle owned by user", "example": true }, "insuredVehicleOwnerName": { "type": "string", "description": "Vehicle owner name if not user", "example": "ABC Leasing Company" }, "insuredVehicleOwnerAddress": { "type": "string", "description": "Vehicle owner address", "example": "789 Business Park" }, "insuredVehicleOwnerPhone": { "type": "string", "description": "Vehicle keeper's phone, collected during documentation when the fleet vehicle record has none", "example": "+43 1 5550000" }, "insuredVehiclePreviousDamage": { "type": "string", "description": "Vehicle previous damage", "example": "Minor scratch on rear door" }, "insuredVehicleFinanceCompany": { "type": "string", "description": "Vehicle finance company", "example": "Auto Finance Corp" }, "insuredParentSpousePhone": { "type": "string", "description": "Insured parent or spouse phone", "example": "+1234567890" }, "reportedToPolice": { "type": "boolean", "description": "Was reported to police", "example": true }, "policeConstableName": { "type": "string", "description": "Police constable name", "example": "Officer Smith" }, "policeConstableBadgeNumber": { "type": "string", "description": "Police constable badge number", "example": "12345" }, "policeConstableTime": { "type": "string", "description": "Police constable time", "example": "14:45" }, "warningOfProsecution": { "type": "boolean", "description": "Warning of prosecution", "example": false }, "prosecutionAgainst": { "type": "string", "description": "Prosecution against", "example": "Driver B" }, "weatherConditions": { "type": "string", "description": "Weather conditions", "example": "Clear" }, "weatherPrecipitationAmount": { "type": "number", "description": "Weather precipitation amount", "example": 0 }, "weatherSymbolCode": { "type": "string", "description": "Weather symbol code", "example": "01d" }, "weatherWindSpeed": { "type": "number", "description": "Weather wind speed", "example": 15.5 }, "weatherAirTemperature": { "type": "number", "description": "Weather air temperature", "example": 22.5 }, "speedVehicleA": { "type": "string", "description": "Speed of vehicle A", "example": "50 km/h" }, "speedVehicleB": { "type": "string", "description": "Speed of vehicle B", "example": "60 km/h" }, "warningsGiven": { "type": "string", "description": "Warnings given", "example": "Stop sign visible" }, "streetLightsIlluminated": { "type": "boolean", "description": "Street lights illuminated", "example": false }, "lightsDisplayed": { "type": "string", "description": "Lights displayed", "example": "Headlights on" }, "vehicleLoadWeight": { "type": "string", "description": "Vehicle load weight", "example": "500kg" }, "signatureDocumentId": { "type": "string", "description": "Digital signer document ID", "example": "DOC-123456" }, "signatureRequestCompleted": { "type": "boolean", "description": "Digital signer signature request completed", "example": true }, "signatureRequestId": { "type": "string", "description": "Digital signer signature request ID", "example": "REQ-789012" }, "signatureUrl": { "type": "string", "description": "Digital signer sign URL", "example": "https://signing.crashwise.app/s/abc123" }, "signers": { "type": "array", "description": "Digital signer individual signer URLs (stored as JSON)", "example": [ { "email": "driver@example.com", "role": "John Doe", "signUrl": "https://signing.crashwise.app/s/abc123", "signed": false }, { "email": "opponent@example.com", "role": "Jane Smith", "signUrl": "https://signing.crashwise.app/s/abc123", "signed": false } ], "items": { "type": "string" } }, "signatureEnvelopeId": { "type": "string", "description": "Signature envelope identifier", "example": "envelope_abc123xyz" }, "signatureEnvelopeDocumentId": { "type": "number", "description": "Identifier of the document within the signature envelope", "example": 7 }, "signatureEnvelopeCompleted": { "type": "boolean", "description": "Whether every party has signed the envelope", "example": true }, "signatureEnvelopeStatus": { "type": "string", "description": "Current status of the signature envelope", "example": "COMPLETED" }, "signatureEnvelopeSigners": { "type": "array", "description": "Parties invited to sign, with their individual signing links", "example": [ { "email": "driver@example.com", "name": "John Doe", "role": "SIGNER", "token": "abc123", "signUrl": "https://signing.crashwise.app/s/abc123", "signed": false, "recipientId": 1 }, { "email": "opponent@example.com", "name": "Jane Smith", "role": "SIGNER", "token": "xyz789", "signUrl": "https://signing.crashwise.app/s/abc123", "signed": false, "recipientId": 2 } ], "items": { "type": "string" } }, "signatureUninvitedSigners": { "type": "array", "description": "Parties that were left out of the signature request because their address already belongs to another signer. Written with the signer list on every request, so it always describes the request that was actually sent.", "example": [ { "name": "Jane Smith", "email": "office@example.com" } ], "items": { "type": "string" } }, "copyEmailsSentAt": { "type": "string", "description": "When the unsigned report copy stopped having anything left to deliver — every participant was reached or given up on", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "signedCopyEmailsSentAt": { "type": "string", "description": "When the signed report copy stopped having anything left to deliver — see copyEmailsSentAt", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "reportCopyDeliveries": { "type": "array", "description": "Per-recipient delivery state of the report copy emails, so a partial failure retries only the recipients it missed", "example": [ { "kind": "signed", "email": "driver@example.com", "sentAt": "2024-01-15T14:30:00.000Z", "attempts": 1 } ], "items": { "type": "string" } }, "signatureCompletedAt": { "type": "string", "description": "When every party had signed and the document was sealed", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "completedAt": { "type": "string", "description": "When the reporting driver closed the accident documentation at the scene", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "completedByUserId": { "type": "string", "description": "The user who closed the accident documentation" }, "driverLanguage": { "type": "string", "description": "Language the reporting driver documented the accident in. Drives the secondary translation lines in the report PDF.", "example": "pl" }, "summaryText": { "type": "string", "description": "AI-generated neutral summary of the report. System-generated after all parties signed; not editable by users." }, "summaryGeneratedAt": { "type": "string", "description": "When the AI summary was last generated", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "summaryLanguage": { "type": "string", "description": "Language code the AI summary was generated in", "example": "de" }, "summaryModelVersion": { "type": "string", "description": "Model identifier used to generate the AI summary" }, "summaryStale": { "type": "boolean", "description": "True when the summary must be (re)generated: set at finalization and on edits of a finalized report; cleared when generation succeeds." }, "summaryAttempts": { "type": "number", "description": "Number of failed generation attempts since the summary last went stale. Reset to 0 on success, on a fresh stale-mark, and on finalization; the retry cron gives up once it reaches the cap." }, "accidentReportStatusId": { "type": "string", "description": "Accident report status ID", "example": "STATUS-001" }, "timezoneOffsetHours": { "type": "number", "description": "Timezone offset in hours from UTC (e.g., GMT+3 = 3, GMT-5 = -5). Used to display the accident time in user's local timezone. the mobile application should send the device timezone offset.", "example": 3 }, "obstacle": { "type": "string", "description": "Obstacle description", "example": "Street sign" }, "dateSignedOffsetHours": { "type": "string", "description": "Date signed with offset hours", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "remarks": { "type": "string", "description": "Remarks/additional notes", "example": "Additional information about the accident" }, "created": { "type": "string", "description": "The date when the report was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updated": { "type": "string", "description": "The date when the report was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deleted": { "type": "string", "description": "The date when the report was deleted (soft delete)", "example": null, "format": "date-time" }, "streetPositioning": { "type": "object", "description": "Street positioning extracted from the crash assistant, used to auto-place vehicles on the sketch", "additionalProperties": true }, "opponents": { "type": "array", "description": "List of opponents involved in the accident", "items": { "type": "array" } }, "witnesses": { "type": "array", "description": "List of witnesses to the accident", "items": { "type": "array" } } }, "required": [ "id", "organizationId", "organization", "userId", "user", "organizationVehicleId", "organizationVehicle", "isAnotherVehicleInvolved", "dateAndTime", "location", "driverFirstName", "driverLastName", "hasInjuries", "hasPropertyDamage", "reportedToPolice", "created", "updated" ] }, "ValidationErrorDto": { "type": "object", "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the offending member of the request body, or the name of the offending query parameter.", "example": "/vehicle/vin" }, "detail": { "type": "string", "description": "What is wrong with this field.", "example": "must be a 17-character vehicle identification number" }, "code": { "type": "string", "description": "Machine-readable code for this specific field failure.", "example": "invalid_format" } }, "required": [ "pointer", "detail" ] }, "ValidationProblemDetailsDto": { "type": "object", "properties": { "type": { "type": "string", "description": "A URI identifying the problem type. Dereference it for a human-readable explanation of this class of error.", "example": "https://api.public.crashwise.app/docs/errors/unauthorized" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type.", "example": "Unauthorized" }, "status": { "type": "number", "description": "The HTTP status code for this occurrence of the problem.", "example": 401 }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem.", "example": "The access token is missing, expired, or does not grant the required scope." }, "instance": { "type": "string", "description": "The path of the request that produced this problem.", "example": "/v1/reports" }, "requestId": { "type": "string", "description": "A unique identifier for this request. Quote it when contacting support — it is the fastest way for us to find the corresponding log entry.", "example": "req_01JBQ7K3M9XN4P2VYD8ZFA6RTC" }, "code": { "type": "string", "description": "A stable, machine-readable error code. Use this rather than parsing `detail`, which may be reworded.", "example": "insufficient_scope" }, "errors": { "description": "One entry per field that failed validation.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorDto" } } }, "required": [ "type", "title", "status", "detail", "instance", "requestId", "errors" ] }, "UpdateReportDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The UUID of the organization", "example": "550e8400-e29b-41d4-a716-446655440001" }, "userId": { "type": "string", "description": "The UUID of the reporting user", "example": "550e8400-e29b-41d4-a716-446655440002" }, "organizationVehicleId": { "type": "string", "description": "UUID of vehicle A (organization vehicle)", "example": "550e8400-e29b-41d4-a716-446655440003" }, "isAnotherVehicleInvolved": { "type": "boolean", "description": "Whether another vehicle is involved in the accident", "example": true }, "otherVehicleVin": { "type": "string", "description": "Other vehicle VIN (only when isAnotherVehicleInvolved is true)", "example": "5FNRL5H63DB123456" }, "otherVehicleManufacturer": { "type": "string", "description": "Other vehicle manufacturer (only when isAnotherVehicleInvolved is true)", "example": "Honda" }, "otherVehicleModel": { "type": "string", "description": "Other vehicle model (only when isAnotherVehicleInvolved is true)", "example": "Civic" }, "otherVehicleType": { "type": "string", "description": "Other vehicle type (only when isAnotherVehicleInvolved is true)", "example": "Sedan" }, "otherVehicleRegistrationNumber": { "type": "string", "description": "Other vehicle registration number (only when isAnotherVehicleInvolved is true)", "example": "XYZ-5678" }, "otherVehicleColor": { "type": "string", "description": "Other vehicle color (only when isAnotherVehicleInvolved is true)", "example": "Red" }, "otherVehicleDisplacementCCM": { "type": "number", "description": "Other vehicle displacement CCM (only when isAnotherVehicleInvolved is true)", "example": 1998 }, "otherVehicleFuelType": { "type": "string", "description": "Other vehicle fuel type (only when isAnotherVehicleInvolved is true)", "example": "Petrol" }, "otherVehicleMassInService": { "type": "number", "description": "Other vehicle mass in service (only when isAnotherVehicleInvolved is true)", "example": 1500 }, "otherVehicleMaxMass": { "type": "number", "description": "Other vehicle max mass (only when isAnotherVehicleInvolved is true)", "example": 2000 }, "otherVehiclePowerKW": { "type": "number", "description": "Other vehicle power kW (only when isAnotherVehicleInvolved is true)", "example": 110 }, "otherVehicleSeatsNumber": { "type": "number", "description": "Other vehicle seats number (only when isAnotherVehicleInvolved is true)", "example": 5 }, "otherVehicleInsuranceCompany": { "type": "string", "description": "Other vehicle insurance company (only when isAnotherVehicleInvolved is true)", "example": "State Farm" }, "otherVehicleInsurancePolicyNumber": { "type": "string", "description": "Other vehicle insurance policy number (only when isAnotherVehicleInvolved is true)", "example": "POL-789012" }, "otherVehicleInsuranceCompany2": { "type": "string", "description": "Other vehicle secondary insurance company (only when isAnotherVehicleInvolved is true)", "example": "Allstate" }, "otherVehicleInsurancePolicyNumber2": { "type": "string", "description": "Other vehicle secondary insurance policy number (only when isAnotherVehicleInvolved is true)", "example": "POL-345678" }, "otherVehicleOwnerFirstName": { "type": "string", "description": "Other vehicle owner first name (only when isAnotherVehicleInvolved is true)", "example": "Jane" }, "otherVehicleOwnerLastName": { "type": "string", "description": "Other vehicle owner last name (only when isAnotherVehicleInvolved is true)", "example": "Smith" }, "otherVehicleOwnerPhone": { "type": "string", "description": "Other vehicle owner phone (only when isAnotherVehicleInvolved is true)", "example": "+1234567890" }, "otherVehicleOwnerEmail": { "type": "string", "description": "Other vehicle owner email (only when isAnotherVehicleInvolved is true)", "example": "jane@example.com" }, "otherVehicleOwnerAddress": { "type": "string", "description": "Other vehicle owner address (only when isAnotherVehicleInvolved is true)", "example": "456 Oak St" }, "otherVehicleInsuredIsCompany": { "type": "boolean", "description": "Whether the other vehicle owner is a company (only when isAnotherVehicleInvolved is true)", "example": false }, "otherVehicleInsuredCompanyName": { "type": "string", "description": "Other vehicle company name if owner is a company (only when isAnotherVehicleInvolved is true)", "example": "ABC Company Ltd" }, "otherVehicleInitialPointOfImpact": { "type": "string", "description": "Other vehicle point of impact (only when isAnotherVehicleInvolved is true)", "example": "Rear bumper" }, "otherVehicleSecondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones on the other vehicle besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "otherVehicleVisibleDamage": { "type": "string", "description": "Other vehicle visible damage (only when isAnotherVehicleInvolved is true)", "example": "Rear bumper damaged" }, "otherDriverLanguage": { "type": "string", "description": "Other vehicle language (only when isAnotherVehicleInvolved is true)", "example": "English" }, "otherDriverFirstName": { "type": "string", "description": "Other vehicle driver first name (only when isAnotherVehicleInvolved is true)", "example": "Jane" }, "otherDriverLastName": { "type": "string", "description": "Other vehicle driver last name (only when isAnotherVehicleInvolved is true)", "example": "Smith" }, "otherDriverAddress": { "type": "string", "description": "Other vehicle driver address (only when isAnotherVehicleInvolved is true)", "example": "456 Oak St, Los Angeles, CA 90001" }, "otherDriverEmail": { "type": "string", "description": "Other vehicle driver personal email (only when isAnotherVehicleInvolved is true)", "example": "other.driver@example.com" }, "otherDriverPhone": { "type": "string", "description": "Other vehicle driver personal phone (only when isAnotherVehicleInvolved is true)", "example": "+1 555 987 6543" }, "otherDriverZipCode": { "type": "string", "description": "Other vehicle driver zip code (only when isAnotherVehicleInvolved is true)", "example": "90001" }, "otherDriverCity": { "type": "string", "description": "Other vehicle driver city (only when isAnotherVehicleInvolved is true)", "example": "Los Angeles" }, "otherDriverCountry": { "type": "string", "description": "Other vehicle driver country (only when isAnotherVehicleInvolved is true)", "example": "United States" }, "otherDriverLicenceNumber": { "type": "string", "description": "Other vehicle driver licence number (only when isAnotherVehicleInvolved is true)", "example": "DL789012" }, "otherDriverLicenceGroups": { "type": "array", "description": "Other vehicle driver licence groups (only when isAnotherVehicleInvolved is true) - can be array or comma-separated string", "example": [ "B", "BE" ], "items": { "type": "string" } }, "otherDriverLicenceIssuedBy": { "type": "string", "description": "Other vehicle driver licence issued by (only when isAnotherVehicleInvolved is true)", "example": "DMV California" }, "otherDriverLicenceValidFrom": { "type": "string", "description": "Other vehicle driver licence valid from (only when isAnotherVehicleInvolved is true)", "example": "2019-06-01" }, "otherDriverLicenceValidTo": { "type": "string", "description": "Other vehicle driver licence valid to (only when isAnotherVehicleInvolved is true)", "example": "2029-06-01" }, "otherDriverDob": { "type": "string", "description": "Other vehicle driver date of birth (only when isAnotherVehicleInvolved is true)", "example": "1985-03-20" }, "otherDriverSignature": { "type": "string", "description": "Other vehicle driver signature (only when isAnotherVehicleInvolved is true)", "example": "data:image/png;base64,..." }, "dateAndTime": { "type": "string", "description": "Date and time of the accident in user's local timezone (e.g., \"2024-01-15T14:30:00\"). The backend will convert this to UTC using timezoneOffsetHours.", "example": "2024-01-15T14:30:00" }, "location": { "type": "string", "description": "Location of the accident", "example": "Main Street and 5th Avenue" }, "locationLat": { "type": "number", "description": "Latitude", "example": 40.7128 }, "locationLng": { "type": "number", "description": "Longitude", "example": -74.006 }, "locationCountry": { "type": "string", "description": "Country where accident occurred", "example": "United States" }, "driverFirstName": { "type": "string", "description": "Driver first name", "example": "John" }, "driverLastName": { "type": "string", "description": "Driver last name", "example": "Doe" }, "driverAddress": { "type": "string", "description": "Driver address", "example": "123 Main St" }, "driverEmail": { "type": "string", "description": "Driver personal email", "example": "driver@example.com" }, "driverPhone": { "type": "string", "description": "Driver personal phone", "example": "+1 555 123 4567" }, "driverZipCode": { "type": "string", "description": "Driver zip code", "example": "10001" }, "driverCity": { "type": "string", "description": "Driver city", "example": "New York" }, "driverCountry": { "type": "string", "description": "Driver country", "example": "United States" }, "driverLicenceNumber": { "type": "string", "description": "Driver licence number", "example": "DL123456" }, "driverLicenceGroups": { "type": "array", "description": "Driver licence groups (can be array or comma-separated string)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "driverLicenceIssuedBy": { "type": "string", "description": "Driver licence issued by", "example": "DMV New York" }, "driverLicenceValidFrom": { "type": "string", "description": "Driver licence valid from", "example": "2020-01-01" }, "driverLicenceValidTo": { "type": "string", "description": "Driver licence valid to", "example": "2030-01-01" }, "driverSignature": { "type": "string", "description": "Driver signature", "example": "data:image/png;base64,..." }, "driverOccupation": { "type": "string", "description": "Driver occupation", "example": "Engineer" }, "driverDob": { "type": "string", "description": "Driver date of birth", "example": "1990-05-15" }, "driverTheoryTestPassed": { "type": "boolean", "description": "Driver theory test passed", "example": true }, "driverDrivingWithPermission": { "type": "boolean", "description": "Driver driving with permission", "example": true }, "driverIsEmployee": { "type": "boolean", "description": "Driver is employee", "example": true }, "driverHasDisabilities": { "type": "boolean", "description": "Driver has disabilities", "example": false }, "hasInjuries": { "type": "boolean", "description": "Has injuries", "example": false }, "injuriesDescription": { "type": "string", "description": "Injuries description", "example": "Minor cuts" }, "hasPropertyDamage": { "type": "boolean", "description": "Has property damage", "example": true }, "propertyDamageDescription": { "type": "string", "description": "Property damage description", "example": "Front bumper damaged" }, "accidentDescription": { "type": "string", "description": "Accident description", "example": "Vehicle A was proceeding..." }, "accidentPlan": { "type": "string", "description": "Accident plan/diagram", "example": "data:image/png;base64,..." }, "initialPointOfImpact": { "type": "string", "description": "Point of initial impact on vehicle A", "example": "Front left" }, "secondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones on vehicle A besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "reportedToPolice": { "type": "boolean", "description": "Reported to police", "example": true }, "policeConstableName": { "type": "string", "description": "Police constable name", "example": "Officer Smith" }, "policeConstableBadgeNumber": { "type": "string", "description": "Police constable badge number", "example": "12345" }, "policeConstableTime": { "type": "string", "description": "Police constable time", "example": "14:45" }, "warningOfProsecution": { "type": "boolean", "description": "Warning of prosecution", "example": false }, "prosecutionAgainst": { "type": "string", "description": "Prosecution against", "example": "Driver B" }, "weatherConditions": { "type": "string", "description": "Weather conditions", "example": "Clear" }, "weatherAirTemperature": { "type": "number", "description": "Weather air temperature in Celsius", "example": 22.5 }, "weatherPrecipitationAmount": { "type": "number", "description": "Weather precipitation amount", "example": 0 }, "weatherSymbolCode": { "type": "string", "description": "Weather symbol code", "example": "01d" }, "weatherWindSpeed": { "type": "number", "description": "Weather wind speed in km/h", "example": 15.5 }, "weatherVisibility": { "type": "number", "description": "Visibility in meters", "example": 10000 }, "weatherRoadConditions": { "type": "string", "description": "Road surface conditions", "example": "Dry" }, "weatherPrecipitation": { "type": "string", "description": "Precipitation type", "example": "None" }, "weatherHumidity": { "type": "number", "description": "Humidity percentage", "example": 65 }, "speedVehicleA": { "type": "string", "description": "Speed of vehicle A", "example": "50 km/h" }, "speedVehicleB": { "type": "string", "description": "Speed of vehicle B", "example": "60 km/h" }, "warningsGiven": { "type": "string", "description": "Warnings given", "example": "Stop sign visible" }, "streetLightsIlluminated": { "type": "boolean", "description": "Street lights illuminated", "example": false }, "lightsDisplayed": { "type": "string", "description": "Lights displayed", "example": "Headlights on" }, "vehicleLoadWeight": { "type": "string", "description": "Vehicle load weight", "example": "500kg" }, "obstacle": { "type": "string", "description": "Obstacle description", "example": "Street sign" }, "visibleDamage": { "type": "string", "description": "Visible damage on vehicle A", "example": "Front bumper" }, "isDamageInsured": { "type": "boolean", "description": "Is damage insured on vehicle A", "example": true }, "insuredVehicleStillInUse": { "type": "boolean", "description": "Insured vehicle still in use", "example": false }, "drivabilityVerdict": { "type": "string", "description": "Outcome of the guided drivability check (CW-1357)", "example": "not_roadworthy", "enum": [ "not_roadworthy", "restricted", "roadworthy" ] }, "drivabilityFindings": { "type": "array", "description": "Findings behind the drivability verdict", "example": [ "lighting_failure", "fluid_leak_or_smoke" ], "items": { "type": "string" } }, "drivabilityCheckCompleted": { "type": "boolean", "description": "True when the driver worked through the guided check rather than only answering Yes/No", "example": true }, "insuredVehiclePresentLocation": { "type": "string", "description": "Insured vehicle present location", "example": "Repair shop on 10th Street" }, "insuredVehicleCarryingCapacity": { "type": "string", "description": "Insured vehicle carrying capacity", "example": "5 passengers" }, "insuredVehicleFirstRegistration": { "type": "string", "description": "Insured vehicle first registration date", "example": "2018-03-15" }, "insuredVehicleOwnedByUser": { "type": "boolean", "description": "Insured vehicle owned by user", "example": true }, "insuredVehicleOwnerName": { "type": "string", "description": "Insured vehicle owner name if not user", "example": "ABC Leasing Company" }, "insuredVehicleOwnerAddress": { "type": "string", "description": "Insured vehicle owner address", "example": "789 Business Park" }, "insuredVehicleOwnerPhone": { "type": "string", "description": "Insured vehicle owner phone", "example": "+43 1 5550000" }, "insuredVehiclePreviousDamage": { "type": "string", "description": "Insured vehicle previous damage", "example": "Minor scratch on rear door" }, "insuredVehicleFinanceCompany": { "type": "string", "description": "Insured vehicle finance company", "example": "Auto Finance Corp" }, "insuredParentSpousePhone": { "type": "string", "description": "Insured parent or spouse phone", "example": "+1234567890" }, "signatureDocumentId": { "type": "string", "description": "Digital signer document ID", "example": "DOC-123456" }, "signatureRequestCompleted": { "type": "boolean", "description": "Digital signer signature request completed", "example": true }, "signatureRequestId": { "type": "string", "description": "Digital signer signature request ID", "example": "REQ-789012" }, "signatureUrl": { "type": "string", "description": "Digital signer sign URL", "example": "https://signing.crashwise.app/s/abc123" }, "accidentReportStatusId": { "type": "string", "description": "Accident report status ID", "example": "STATUS-001" }, "timezoneOffsetHours": { "type": "number", "description": "Timezone offset in hours from UTC (e.g., GMT+3 = 3, GMT-5 = -5). **STRONGLY RECOMMENDED** to correctly store and display accident time in PDFs and UI. Without this field, times will be displayed in UTC instead of user's local time. the mobile application should calculate and send device timezone offset using: `new Date().getTimezoneOffset() / -60` (note the negative sign!). Example: If user is in GMT+3, send 3. If user is in GMT-5, send -5.", "example": 3 }, "dateSignedOffsetHours": { "type": "string", "description": "Date signed with offset hours", "example": "2024-01-15T14:30:00.000Z" }, "remarks": { "type": "string", "description": "Remarks", "example": "Additional notes" }, "circumstancesVehicleA": { "type": "array", "description": "Circumstances for Vehicle A (snake_case values)", "example": [ "reversing", "turning_left" ], "items": { "type": "string" } }, "circumstancesVehicleB": { "type": "array", "description": "Circumstances for Vehicle B (snake_case values)", "example": [ "parked" ], "items": { "type": "string" } } } }, "SignerDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email of the signer", "example": "john.doe@example.com" }, "role": { "type": "string", "description": "Role/name of the signer", "example": "Driver" } }, "required": [ "email", "role" ] }, "SignReportDto": { "type": "object", "properties": { "signers": { "description": "List of signers for the report. If not provided, signers will be auto-populated from the report data.", "example": [ { "email": "john.doe@example.com", "role": "Driver" }, { "email": "jane.smith@example.com", "role": "Witness" } ], "type": "array", "items": { "$ref": "#/components/schemas/SignerDto" } }, "subject": { "type": "string", "description": "Subject for the signature request email", "example": "Please sign the accident report" }, "message": { "type": "string", "description": "Message for the signature request email", "example": "Please review and sign the attached accident report." }, "sendEmails": { "type": "boolean", "description": "Whether to send emails to signers immediately", "example": true }, "isSequential": { "type": "boolean", "description": "Whether signers must sign in sequential order", "example": false }, "force": { "type": "boolean", "description": "Re-issue the signature request even though signatures were already collected on the current one. Those signatures are discarded and the parties have to sign again, so only send this after the user has explicitly confirmed it. Without it, such a request is rejected with 409 SIGNATURE_REQUEST_PARTIALLY_SIGNED.", "example": false } } }, "SignReportResponseDto": { "type": "object", "properties": { "signatureRequestId": { "type": "string", "description": "The signature request ID from the e-signature service", "example": "8a19b80f-8480-41a8-8e58-2cdcc5d2ae57" }, "driverSignUrl": { "type": "string", "description": "Signing URL for the primary driver (report creator)", "example": "https://signing.crashwise.app/s/abc123" }, "opponentSigningLinks": { "type": "array", "description": "List of signing URLs for all VEHICLE and PEDESTRIAN type opponents. Obstacles are excluded as they cannot sign.", "items": { "type": "array" } }, "documentId": { "type": "string", "description": "The document ID from the e-signature service", "example": "2966f558-63b7-4ec7-8be3-2f73978ec02c" }, "message": { "type": "string", "description": "Success message", "example": "Signature request sent successfully" }, "otherDriverSignUrl": { "type": "string", "description": "DEPRECATED: Use opponentSigningLinks instead. Kept for backward compatibility.", "example": "https://signing.crashwise.app/s/abc123" }, "uninvitedSigners": { "type": "array", "description": "Parties that were NOT invited because their email address already belongs to another signer. The signing service identifies a recipient by address, so only the first party on a shared mailbox can be invited; the others keep a printed signature line with nobody asked to fill it. Empty in the normal case.", "items": { "type": "array" } } }, "required": [ "signatureRequestId", "driverSignUrl", "opponentSigningLinks", "documentId", "message" ] }, "ShareReportDto": { "type": "object", "properties": { "emails": { "type": "array", "description": "Email addresses to share the report with", "example": [ "john.doe@example.com", "jane.smith@example.com" ], "items": { "type": "string" } }, "message": { "type": "string", "description": "Optional message to include in the email", "example": "Please review this accident report." }, "subject": { "type": "string", "description": "Optional subject for the email", "example": "Accident Report Shared" } }, "required": [ "emails" ] }, "CompleteReportDto": { "type": "object", "properties": { "sendCopyToReporter": { "type": "boolean", "description": "Whether the reporting driver wants a copy of the report emailed to them. The other participants always receive one.", "example": true } } }, "CompleteReportResponseDto": { "type": "object", "properties": { "completedAt": { "type": "string", "description": "When the report was closed", "example": "2024-01-15T14:30:00.000Z", "format": "date-time" }, "copySent": { "type": "boolean", "description": "Whether a copy was emailed as part of this call. False when every send failed, and also when the copy had already been sent earlier (see copyAlreadySent).", "example": true }, "copyAlreadySent": { "type": "boolean", "description": "True when the participants had already been sent a copy before this call (e.g. the report was fully signed and the signed copy went out).", "example": false }, "copyRecipients": { "type": "array", "description": "Names of the participants a copy was addressed to", "example": [ "Max Mustermann", "Anna Beispiel" ], "items": { "type": "string" } }, "recipientsWithoutEmail": { "type": "number", "description": "How many participants could not be sent a copy because no deliverable address is known", "example": 1 }, "pendingSignatures": { "type": "number", "description": "How many requested signatures are still outstanding", "example": 1 } }, "required": [ "completedAt", "copySent", "copyAlreadySent", "copyRecipients", "recipientsWithoutEmail", "pendingSignatures" ] }, "UpdateDocumentDto": { "type": "object", "properties": { "title": { "type": "string", "description": "Display title for the document", "example": "Police Report" }, "description": { "type": "string", "description": "Free-text description of the document", "example": "Official police report filed at the scene." } } }, "CreateSessionDto": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report ID to associate with this session" }, "initialData": { "type": "object", "description": "Pre-collected extracted data (e.g. scene location from safety-check screen)", "additionalProperties": true }, "supportedWidgets": { "type": "array", "description": "Widget types this client can render (capability handshake). Widgets introduced after this handshake are only sent when declared here; omitting the field downgrades those steps to text input.", "example": [ "opponent_count_buttons" ], "items": { "type": "string" } }, "language": { "type": "string", "description": "Language code", "example": "en" }, "enableTTS": { "type": "boolean", "description": "Enable TTS for the greeting" }, "engine": { "type": "string", "description": "TTS engine" }, "speechRate": { "type": "string", "description": "Speech rate" }, "voiceId": { "type": "string", "description": "Specific speech synthesis voice ID" } } }, "DrivabilityChecklistItemDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Finding code (wire contract)", "example": "view_obstructed" }, "label": { "type": "string", "description": "Localized checklist label, examples included" }, "severity": { "type": "string", "description": "`blocking` stops the drive, `restricting` only limits it. Shipped so the sheet can preview the outcome before submitting.", "enum": [ "blocking", "restricting" ] } }, "required": [ "code", "label", "severity" ] }, "DrivabilityCheckDto": { "type": "object", "properties": { "title": { "type": "string", "description": "Sheet heading" }, "cta": { "type": "string", "description": "Label for the row that opens the sheet" }, "hintSuspected": { "type": "string", "description": "Shown under the CTA when the damage already implies a finding" }, "safetyNote": { "type": "string", "description": "Why the check matters, in safety terms. Deliberately carries no legal text: the app gives guidance, not a legal recommendation, and has to read the same in every country." }, "disclaimer": { "type": "string", "description": "Not-legal-advice disclaimer" }, "whyLabel": { "type": "string", "description": "Label for the sheet's \"why?\" disclosure" }, "evaluateLabel": { "type": "string", "description": "Label for the button that reveals the outcome" }, "verdicts": { "type": "object", "description": "Localized verdict headlines, so the sheet can name the outcome it previews without the app carrying its own copy of the wording.", "example": { "not_roadworthy": "Do not drive this vehicle", "restricted": "Drive on only under restrictions", "roadworthy": "No blocking defects found" }, "additionalProperties": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/DrivabilityChecklistItemDto" } } }, "required": [ "title", "cta", "hintSuspected", "safetyNote", "disclaimer", "whyLabel", "evaluateLabel", "verdicts", "items" ] }, "StepInfoDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Step identifier", "example": "injuries" }, "question": { "type": "string", "description": "Localized question text for this step", "example": "Was anyone hurt in the accident?" }, "widget": { "type": "string", "description": "Widget to display for this step (null = text/voice only)", "example": "scene_buttons" }, "inputType": { "type": "string", "description": "Input type for this step", "example": "text_or_voice", "enum": [ "text_or_voice", "widget", "widget_and_text" ] }, "canSkip": { "type": "boolean", "description": "Whether this step can be skipped", "example": false }, "widgetField": { "type": "string", "description": "For widget=boolean_buttons: which boolean field the Yes/No buttons populate", "example": "hasWitnesses" }, "singleVehicleWording": { "type": "boolean", "description": "For widget=vehicle_position: true when the wording must be singular (no opponent vehicle at the scene — single-vehicle, pedestrian-only, or hit-and-run). Authoritative — the client must not re-derive it.", "example": false }, "suspectedDrivabilityFindings": { "type": "array", "description": "For widget=drivability_check: findings the damage data already implies, used to pre-tick the checklist and to explain why the check is being suggested. Suggestions only — the driver has to confirm them, and the server never counts them towards the verdict on their own.", "example": [ "view_obstructed" ], "items": { "type": "string" } }, "drivabilityCheck": { "description": "For widget=drivability_check: everything the sheet renders — the checklist plus its copy, all localized. Server-owned so the app, the PDF and the the web application can never name the same item differently, and a reworded item reaches installed apps without a release.", "allOf": [ { "$ref": "#/components/schemas/DrivabilityCheckDto" } ] }, "photoGuidance": { "type": "object", "description": "Photo guidance data for the damage_photos step", "additionalProperties": true } }, "required": [ "id", "question", "widget", "inputType", "canSkip" ] }, "ProgressDto": { "type": "object", "properties": { "completedSteps": { "type": "number", "description": "Number of completed steps", "example": 5 }, "totalSteps": { "type": "number", "description": "Total applicable steps", "example": 14 }, "percentage": { "type": "number", "description": "Completion percentage", "example": 36 } }, "required": [ "completedSteps", "totalSteps", "percentage" ] }, "PoliceAdvisoryDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Policy reason that triggered the advice", "example": "hit_and_run" }, "severity": { "type": "string", "description": "How urgent the advice is: officers needed at the scene now, or the incident has to be reported without waiting at the roadside", "example": "inform", "enum": [ "call_to_scene", "inform" ] }, "isNew": { "type": "boolean", "description": "True when the assistant advised on this reason for the first time", "example": true }, "text": { "type": "string", "description": "The advice sentence itself, in the conversation language. It is also the assistant bubble the card belongs to, which is how a resumed session finds that bubble again in the rebuilt history (CW-1584).", "example": "This is a hit-and-run. Please report it to the police." } }, "required": [ "reason", "severity", "isNew" ] }, "DrivabilityAdvisoryDto": { "type": "object", "properties": { "verdict": { "type": "string", "description": "Outcome of the guided drivability check, or of a plain \"not drivable\" answer. Only sent when there is something to warn about.", "example": "not_roadworthy", "enum": [ "not_roadworthy", "restricted", "roadworthy" ] }, "findings": { "type": "array", "description": "Findings the driver confirmed, in canonical order. `user_reported` means they answered \"not drivable\" without working through the check.", "example": [ "lighting_failure", "fluid_leak_or_smoke" ], "items": { "type": "string" } }, "isNew": { "type": "boolean", "description": "True when the assistant advised on this outcome for the first time", "example": true }, "text": { "type": "string", "description": "The advice sentence as it appears in the chat — a different string from `headline`, and the one that identifies the assistant bubble this card belongs to when a resumed session rebuilds the history (CW-1584).", "example": "Based on what you told us, do not drive this vehicle. Please have it collected." }, "headline": { "type": "string", "description": "Localized headline for the verdict, e.g. \"Do not drive this vehicle\"", "example": "Do not drive this vehicle" }, "findingLabels": { "type": "array", "description": "Localized labels for `findings`, in the same order. Server-owned so the card names an item exactly as the checklist did.", "example": [ "Lights not working — indicators, brake lights or headlights" ], "items": { "type": "string" } }, "safetyNote": { "type": "string", "description": "Why the check matters, in safety terms — never legal text" }, "disclaimer": { "type": "string", "description": "Not-legal-advice disclaimer shown next to the safety note" }, "whyLabel": { "type": "string", "description": "Label for the card's \"why?\" action" } }, "required": [ "verdict", "findings", "isNew", "headline", "findingLabels", "safetyNote", "disclaimer", "whyLabel" ] }, "SessionResponseDto": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session identifier", "example": "550e8400-e29b-41d4-a716-446655440000" }, "currentStep": { "description": "Current step info", "allOf": [ { "$ref": "#/components/schemas/StepInfoDto" } ] }, "aiResponse": { "type": "string", "description": "AI response text (acknowledgment + optional clarification)", "example": "I'm sorry to hear about the damage." }, "assistantMessages": { "type": "array", "description": "The assistant turn split into one chat bubble per message, in order. Present whenever the turn carries more than the question alone — today that is police advice, which gets its own bubble so the user is never given two tasks at once (CW-1584). Clients that understand this field MUST render these instead of aiResponse; aiResponse keeps the combined text for app builds that predate the field.", "example": [ "Understood. Someone else's property was damaged — please report it to the police.", "What visible damage does your car have?" ], "items": { "type": "string" } }, "audioResponseBase64": { "type": "string", "description": "TTS audio as base64 MP3 (only if voice mode)" }, "audioContentType": { "type": "string", "description": "Audio content type", "example": "audio/mpeg" }, "transcribedText": { "type": "string", "description": "Transcribed text from audio input (only for audio processing)" }, "extractedData": { "type": "object", "description": "Full extracted data snapshot", "additionalProperties": true }, "progress": { "description": "Progress through the flow", "allOf": [ { "$ref": "#/components/schemas/ProgressDto" } ] }, "canGoBack": { "type": "boolean", "description": "Whether the user can go back to a previous step", "example": true }, "isComplete": { "type": "boolean", "description": "Whether the entire flow is complete", "example": false }, "policeRequired": { "type": "boolean", "description": "Whether police reporting is required", "example": false }, "policeRequiredReason": { "type": "string", "description": "Reason for police requirement", "example": "hit_and_run" }, "policeAdvisory": { "description": "Police advice to surface in the chat. `isNew` is true when the assistant just advised on this reason for the first time (the accompanying sentence is the first entry of assistantMessages, and part of aiResponse for older clients); false when it is an outstanding advisory returned on session resume.", "allOf": [ { "$ref": "#/components/schemas/PoliceAdvisoryDto" } ] }, "drivabilityAdvisory": { "description": "Drivability advice. isNew=true when raised for the first time (the accompanying sentence is part of aiResponse); false when it is an outstanding advisory returned on session resume.", "allOf": [ { "$ref": "#/components/schemas/DrivabilityAdvisoryDto" } ] }, "conversationHistory": { "type": "array", "description": "Full conversation history for session resume (only included on GET session state)", "items": { "type": "object" } } }, "required": [ "sessionId", "currentStep", "aiResponse", "extractedData", "progress", "canGoBack", "isComplete", "policeRequired" ] }, "LinkReportDto": { "type": "object", "properties": { "reportId": { "type": "string", "description": "Report to attach to this session", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "reportId" ] }, "LinkReportResponseDto": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "Session identifier" }, "reportId": { "type": "string", "description": "Report now linked to the session" } }, "required": [ "sessionId", "reportId" ] }, "AnswerTextDto": { "type": "object", "properties": { "text": { "type": "string", "description": "User text answer", "example": "A blue BMW ran a red light and hit my front bumper." }, "idempotencyKey": { "type": "string", "description": "Idempotency key to prevent duplicate processing", "example": "msg-123-abc" }, "enableTTS": { "type": "boolean", "description": "Enable text-to-speech audio response" }, "engine": { "type": "string", "description": "TTS engine" }, "speechRate": { "type": "string", "description": "Speech rate" }, "voiceId": { "type": "string", "description": "Specific speech synthesis voice ID" } }, "required": [ "text" ] }, "AnswerWidgetDto": { "type": "object", "properties": { "data": { "type": "object", "description": "Widget data payload (structure depends on widget type)", "example": { "isAtAccidentScene": true, "locationLat": 52.52, "locationLng": 13.405 }, "additionalProperties": true }, "idempotencyKey": { "type": "string", "description": "Idempotency key to prevent duplicate processing" }, "enableTTS": { "type": "boolean", "description": "Enable text-to-speech audio response" }, "engine": { "type": "string", "description": "TTS engine" }, "speechRate": { "type": "string", "description": "Speech rate" }, "voiceId": { "type": "string", "description": "Specific speech synthesis voice ID" } }, "required": [ "data" ] }, "AddressDto": { "type": "object", "properties": { "street": { "type": "string", "description": "Street address", "example": "123 Main St" }, "city": { "type": "string", "description": "City", "example": "New York" }, "zipcode": { "type": "string", "description": "Zipcode", "example": "10001" }, "country": { "type": "string", "description": "Country", "example": "United States" } } }, "CreateDrivingLicenceDto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name on the driving licence", "example": "John" }, "lastName": { "type": "string", "description": "Last name on the driving licence", "example": "Doe" }, "address": { "description": "Address on the driving licence", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "number": { "type": "string", "description": "Driving licence number", "example": "DL-123456789" }, "groups": { "type": "array", "description": "Driving licence groups/categories (can be array or comma-separated string)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "issuer": { "type": "string", "description": "Issuing authority", "example": "Department of Motor Vehicles" }, "validFrom": { "type": "string", "description": "Date when the licence becomes valid (YYYY-MM-DD)", "example": "2020-01-01" }, "validTo": { "type": "string", "description": "Date when the licence expires (YYYY-MM-DD)", "example": "2030-01-01" }, "userId": { "type": "string", "description": "The UUID of the user who owns this driving licence", "example": "550e8400-e29b-41d4-a716-446655440001" } }, "required": [ "firstName", "lastName", "number", "groups", "issuer", "userId" ] }, "DrivingLicenceDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the driving licence", "example": "550e8400-e29b-41d4-a716-446655440000" }, "firstName": { "type": "string", "description": "First name on the driving licence", "example": "John" }, "lastName": { "type": "string", "description": "Last name on the driving licence", "example": "Doe" }, "address": { "type": "object", "description": "Address on the driving licence", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "additionalProperties": true }, "number": { "type": "string", "description": "Driving licence number", "example": "DL-123456789" }, "groups": { "type": "array", "description": "Driving licence groups/categories (e.g., A, B, C)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "issuer": { "type": "string", "description": "Issuing authority", "example": "Department of Motor Vehicles" }, "validFrom": { "type": "string", "description": "Date when the licence becomes valid", "example": "2020-01-01", "format": "date-time" }, "validTo": { "type": "string", "description": "Date when the licence expires", "example": "2030-01-01", "format": "date-time" }, "userId": { "type": "string", "description": "The UUID of the user who owns this driving licence", "example": "550e8400-e29b-41d4-a716-446655440001" }, "user": { "description": "The user who owns this driving licence", "allOf": [ { "$ref": "#/components/schemas/UserDto" } ] }, "createdAt": { "type": "string", "description": "The date when the driving licence was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date when the driving licence was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deletedAt": { "type": "string", "description": "The date when the driving licence was deleted (soft delete)", "example": null, "format": "date-time" } }, "required": [ "id", "firstName", "lastName", "number", "groups", "issuer", "userId", "user", "createdAt", "updatedAt" ] }, "UpdateDrivingLicenceDto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First name on the driving licence", "example": "John" }, "lastName": { "type": "string", "description": "Last name on the driving licence", "example": "Doe" }, "address": { "description": "Address on the driving licence", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "number": { "type": "string", "description": "Driving licence number", "example": "DL-123456789" }, "groups": { "type": "array", "description": "Driving licence groups/categories (can be array or comma-separated string)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "issuer": { "type": "string", "description": "Issuing authority", "example": "Department of Motor Vehicles" }, "validFrom": { "type": "string", "description": "Date when the licence becomes valid (YYYY-MM-DD)", "example": "2020-01-01" }, "validTo": { "type": "string", "description": "Date when the licence expires (YYYY-MM-DD)", "example": "2030-01-01" }, "userId": { "type": "string", "description": "The UUID of the user who owns this driving licence", "example": "550e8400-e29b-41d4-a716-446655440001" } } }, "FileUploadResponseDto": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Upload UUID", "example": "550e8400e29b41d4a716446655440000" }, "fileUrl": { "type": "string", "description": "File URL", "example": "https://files.crashwise.app/ORG123/uploads/file.jpg" }, "thumbnailUrl": { "type": "string", "description": "Thumbnail URL", "example": "https://files.crashwise.app/ORG123/uploads/file_thumb.jpg" } }, "required": [ "uuid", "fileUrl" ] }, "DriversLicenseScanMetaDto": { "type": "object", "properties": { "countryCode": { "type": "string", "description": "Country profile used", "example": "DE" }, "variantId": { "type": "string", "description": "Licence format used", "example": "de-licence-eu-card" }, "countrySource": { "type": "string", "description": "Where the country came from", "example": "detected", "enum": [ "user", "detected", "default" ] }, "warnings": { "type": "array", "description": "Non-fatal issues: categories that could not be confirmed, unreadable dates, disagreements with the machine-readable zone.", "items": { "type": "string" } } }, "required": [ "countrySource", "warnings" ] }, "DriversLicenseScanResponseDto": { "type": "object", "properties": { "result": { "type": "object", "description": "Parsed driver license fields", "example": { "surname": "Smith", "givenNames": "John", "dateOfBirth": "1990-01-01", "placeOfBirth": "Berlin", "dateOfIssue": "2020-01-01", "dateOfExpiry": "2030-01-01", "issuingAuthority": "Stadt Berlin", "licenseNumber": "1234567890", "categories": "B, BE" }, "additionalProperties": true }, "meta": { "description": "How the document was interpreted. Additive — existing clients may ignore it.", "allOf": [ { "$ref": "#/components/schemas/DriversLicenseScanMetaDto" } ] } }, "required": [ "result" ] }, "LicensePlateScanResponseDto": { "type": "object", "properties": { "result": { "type": "object", "description": "Parsed license plate fields. `licensePlateNumber` is only set when the read cleared the confidence threshold (`readable`). When the photo contains more than one plate, `candidates` lists them all and the client must let the user pick.", "example": { "country": "DE", "licensePlateNumber": "WWW5678", "confidence": 1, "countryConfidence": 0.542, "readable": true, "candidates": [ { "licensePlateNumber": "WWW5678", "country": "DE", "confidence": 1, "countryConfidence": 0.542, "detectionConfidence": 0.914, "box": { "xmin": 912, "ymin": 250, "xmax": 1218, "ymax": 321 } }, { "licensePlateNumber": "BBB1234", "country": "DE", "confidence": 1, "countryConfidence": 0.905, "detectionConfidence": 0.918, "box": { "xmin": 447, "ymin": 472, "xmax": 600, "ymax": 580 } } ] }, "additionalProperties": true } }, "required": [ "result" ] }, "VehicleScanMetaDto": { "type": "object", "properties": { "countryCode": { "type": "string", "description": "Country profile used", "example": "IT" }, "variantId": { "type": "string", "description": "Form variant used", "example": "it-cdc-1999" }, "countrySource": { "type": "string", "description": "Where the country came from", "example": "detected", "enum": [ "user", "detected", "default" ] }, "ownerFieldSource": { "type": "string", "description": "Which person block filled the owner fields. Registration documents name up to three parties and the operator is preferred over the legal owner.", "example": "certificateHolder", "enum": [ "user", "certificateHolder", "owner" ] }, "rejectionReason": { "type": "string", "description": "Set when the document was refused rather than merely unreadable. PART_II_DOCUMENT means a vehicle title / Part II was photographed instead of the certificate carried in the vehicle.", "enum": [ "PART_II_DOCUMENT" ] }, "warnings": { "type": "array", "description": "Non-fatal issues: values discarded as implausible, unrecognised vocabulary, unreadable dates.", "example": [ "VIN \"WBAZZZ8T9LK5302\" has 15 characters instead of 17 and was discarded" ], "items": { "type": "string" } } }, "required": [ "countrySource", "warnings" ] }, "VehicleScanResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Extraction status", "example": true }, "data": { "type": "object", "description": "Extracted vehicle registration data", "example": { "vin": "1HGBH41JXMN109186", "registrationNumber": "ABC-1234", "make": "Honda", "model": "Civic", "color": "Blue", "powerKw": 110.5, "seats": 5 }, "additionalProperties": true }, "message": { "type": "string", "description": "Error message if extraction failed", "example": "No vehicle data could be extracted from the images" }, "meta": { "description": "How the document was interpreted. Additive — existing clients may ignore it.", "allOf": [ { "$ref": "#/components/schemas/VehicleScanMetaDto" } ] } }, "required": [ "success" ] }, "InsuranceCardScanResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Extraction status", "example": true }, "data": { "type": "object", "description": "Extracted insurance card data", "example": { "policyNumber": "A809698945", "make": "Tesla", "model": "Model 3 Long Range Dual AWD", "insuranceCompany": "Allianz Elementar Versicherungs-Aktiengesellschaft", "ownerFirstName": "Bernhard", "ownerLastName": "Stark", "ownerAddress": "A-1140 Wien, Ziestgasse 2", "registrationNumber": "W-52202I" }, "additionalProperties": true }, "message": { "type": "string", "description": "Error message if extraction failed", "example": "No insurance card data could be extracted from the image" } }, "required": [ "success" ] }, "InsuranceLookupRequestDto": { "type": "object", "properties": { "licensePlate": { "type": "string", "description": "License plate number", "example": "W96841Y" }, "lookupDate": { "type": "string", "description": "Date for insurance lookup (ISO 8601 format). Defaults to today.", "example": "2024-01-15" }, "countryCode": { "type": "string", "description": "Force country instead of auto-detection", "example": "AT", "enum": [ "AT", "HR", "SK" ] }, "skipCache": { "type": "boolean", "description": "Skip cache and force fresh lookup", "example": false } }, "required": [ "licensePlate" ] }, "InsuranceLookupResponseDto": { "type": "object", "properties": { "status": { "type": "string", "description": "Lookup status", "example": "success", "enum": [ "success", "not_found", "technical_error", "unsupported_country" ] }, "country": { "type": "string", "description": "Detected or specified country", "example": "Austria" }, "countryCode": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)", "example": "AT" }, "insuranceCompany": { "type": "string", "description": "Insurance company name", "example": "Wiener Städtische Versicherung AG" }, "insuranceNumber": { "type": "string", "description": "Insurance policy number", "example": "POL-123456" }, "insuranceEmail": { "type": "string", "description": "Insurance company email", "example": "claims@insurance.at" }, "errorMessage": { "type": "string", "description": "Error message if status is not success", "example": "Failed to connect to insurance database" }, "fromCache": { "type": "boolean", "description": "Whether result was served from cache", "example": true }, "lookupTimestamp": { "type": "string", "description": "Timestamp of the lookup", "example": "2024-01-15T10:30:00.000Z", "format": "date-time" } }, "required": [ "status" ] }, "CreateIssueReportDto": { "type": "object", "properties": { "description": { "type": "string" }, "notifyWhenFixed": { "type": "boolean" }, "contactEmail": { "type": "string" }, "source": { "type": "string", "enum": [ "shake", "settings" ] }, "appVersion": { "type": "string" }, "appBuild": { "type": "string" }, "appVariant": { "type": "string", "enum": [ "development", "preview", "production" ] }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "osVersion": { "type": "string" }, "deviceModel": { "type": "string" }, "locale": { "type": "string" }, "screen": { "type": "string" }, "sentryEventId": { "type": "string" }, "userTimezone": { "type": "string" }, "occurredAt": { "type": "string", "description": "ISO-8601 timestamp" } }, "required": [ "description", "notifyWhenFixed", "source", "appVersion", "appBuild", "appVariant", "platform", "osVersion", "deviceModel", "locale", "userTimezone", "occurredAt" ] }, "CreateMessageDto": { "type": "object", "properties": { "title": { "type": "string", "description": "Message title", "example": "Winter tire reminder" }, "body": { "type": "string", "description": "Message body (plain text)", "example": "Please switch to winter tires by November 1st." }, "targetType": { "type": "string", "description": "Target type", "enum": [ "all", "organization", "drivers", "vehicle" ] }, "targetIds": { "type": "array", "description": "Target IDs (org, driver, or vehicle UUIDs)", "items": { "type": "string" } }, "scheduledAt": { "type": "string", "description": "Schedule send time (ISO 8601). Omit to send immediately." } }, "required": [ "title", "body", "targetType" ] }, "MessageDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Message ID" }, "title": { "type": "string", "description": "Message title", "example": "Winter tire reminder" }, "body": { "type": "string", "description": "Message body (plain text)" }, "senderId": { "type": "string", "description": "ID of the admin who sent the message" }, "organizationId": { "type": "string", "description": "Organization ID (null for cross-org sends)" }, "targetType": { "type": "string", "description": "Target type", "enum": [ "all", "organization", "drivers", "vehicle" ] }, "targetIds": { "type": "array", "description": "Array of target IDs (org, driver, or vehicle UUIDs)", "items": { "type": "string" } }, "status": { "type": "string", "description": "Message status", "enum": [ "draft", "scheduled", "sending", "sent", "cancelled" ] }, "scheduledAt": { "type": "string", "description": "Scheduled send time", "format": "date-time" }, "sentAt": { "type": "string", "description": "Actual send time", "format": "date-time" }, "createdAt": { "type": "string", "description": "Created at", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Updated at", "format": "date-time" } }, "required": [ "id", "title", "body", "senderId", "targetType", "targetIds", "status", "createdAt", "updatedAt" ] }, "CreateOrganizationDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Unique 8-character uppercase code for the organization", "example": "CRASHWIS" }, "name": { "type": "string", "description": "The name of the organization", "example": "Crashwise Inc." }, "defaultLanguage": { "type": "string", "description": "Default language for the organization", "example": "English" }, "defaultLanguageCode": { "type": "string", "description": "Default language code (ISO 639-1)", "example": "en" }, "address": { "description": "Address of the organization", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "driversHaveAccessToAllVehicles": { "type": "boolean", "description": "Whether drivers have access to all vehicles or only assigned ones", "example": true } }, "required": [ "code", "name", "defaultLanguage", "defaultLanguageCode", "address" ] }, "UpdateOrganizationDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Unique 8-character uppercase code for the organization", "example": "CRASHWIS" }, "name": { "type": "string", "description": "The name of the organization", "example": "Crashwise Inc." }, "defaultLanguage": { "type": "string", "description": "Default language for the organization", "example": "English" }, "defaultLanguageCode": { "type": "string", "description": "Default language code (ISO 639-1)", "example": "en" }, "address": { "description": "Address of the organization", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "driversHaveAccessToAllVehicles": { "type": "boolean", "description": "Whether drivers have access to all vehicles or only assigned ones", "example": true } } }, "UpdateNotificationSettingsDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether to email a notification when a new accident report is created", "example": true }, "email": { "type": "string", "description": "Address that receives the new-report notification email", "example": "ops@acme.com" } } }, "UpdateShareContactsDto": { "type": "object", "properties": { "insuranceEmail": { "type": "string", "description": "Insurance address offered when sharing a report. Empty string clears it.", "example": "claims@insurer.com" }, "repairShopEmail": { "type": "string", "description": "Repair shop address offered when sharing a report. Empty string clears it.", "example": "service@workshop.com" } } }, "ValidatePhotoDto": { "type": "object", "properties": { "requestedSubject": { "type": "string", "description": "What the AI asked the user to photograph (e.g. \"close_up_own\", \"insurance_card\", \"opponent_plate\")", "example": "close_up_own" }, "captureStep": { "type": "string", "description": "Which step of the flow the photo was captured in (e.g. \"damage_photos\", \"insurance_card_scan\")", "example": "damage_photos" }, "source": { "type": "string", "description": "Where the photo was captured from", "example": "mobile", "enum": [ "mobile", "guest_web" ] }, "retakeCount": { "type": "number", "description": "How many times the user has retaken this photo (client-tracked, 0 for the first capture)", "example": 0 }, "language": { "type": "string", "description": "BCP-47 / ISO-639-1 language code the user-facing reason should be written in (e.g. \"tr\", \"en\", \"hr\"). Falls back to English when omitted or unsupported.", "example": "tr" } }, "required": [ "requestedSubject", "captureStep", "source" ] }, "PendingReviewPhotoDto": { "type": "object", "properties": { "photoId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "attachmentId": { "type": "number", "description": "Numeric id of the attachment row wrapping this photo. Lets the client delete the superseded original via DELETE /reports/attachments/:attachmentId when a retake replaces it (CW-1120).", "example": 42 }, "status": { "type": "string", "enum": [ "pending", "pass", "warning", "fail" ] }, "reason": { "type": "string", "example": "This photo looks blurry" }, "issues": { "type": "array", "example": [ "blurry" ], "items": { "type": "string" } }, "requestedSubject": { "type": "string", "example": "close_up_own" }, "captureStep": { "type": "string", "example": "damage_photos" }, "retakeCount": { "type": "number", "example": 1 }, "thumbnailUrl": { "type": "string", "example": "https://files.crashwise.app/thumbnails/file-thumbnail.jpg" }, "url": { "type": "string", "example": "https://files.crashwise.app/uploads/file.jpg" } }, "required": [ "photoId", "attachmentId", "status", "reason", "issues", "requestedSubject", "captureStep", "retakeCount", "thumbnailUrl", "url" ] }, "CreateReportOpponentDto": { "type": "object", "properties": { "reportId": { "type": "string", "description": "The UUID of the accident report", "example": "550e8400-e29b-41d4-a716-446655440000" }, "type": { "type": "string", "description": "Type of opponent", "example": "vehicle", "enum": [ "vehicle", "pedestrian", "obstacle" ] }, "source": { "type": "string", "description": "Provenance marker. Clients that auto-create opponents by mirroring AI-extracted crash-assistant data must send crash_assistant_sync so the row can be retracted when the user confirms no other party was involved (CW-1262). Omit for manually entered opponents.", "example": "crash_assistant_sync", "enum": [ "crash_assistant_sync" ] }, "assistantIndex": { "type": "number", "description": "Position of this party in the crash-assistant session (0-based). Send it from every assistant-driven create so a row can be re-paired with its party later; matching by list position mixes parties up as soon as they used different methods (CW-1517). Omit for manual creates.", "example": 2 }, "vehicleVin": { "type": "string", "description": "Vehicle VIN (for vehicle opponents only)", "example": "5FNRL5H63DB123456" }, "vehicleManufacturer": { "type": "string", "description": "Vehicle manufacturer/make (for vehicle opponents only)", "example": "Honda" }, "vehicleModel": { "type": "string", "description": "Vehicle model", "example": "Civic" }, "vehicleType": { "type": "string", "description": "Vehicle type", "example": "Sedan" }, "vehicleRegistrationNumber": { "type": "string", "description": "Vehicle registration/license plate", "example": "XYZ-5678" }, "vehicleColor": { "type": "string", "description": "Vehicle color", "example": "Red" }, "vehicleDisplacementCCM": { "type": "number", "description": "Vehicle displacement in CCM", "example": 1998 }, "vehicleFuelType": { "type": "string", "description": "Vehicle fuel type", "example": "Petrol" }, "vehicleMassInService": { "type": "number", "description": "Vehicle mass in service (kg)", "example": 1500 }, "vehicleMaxMass": { "type": "number", "description": "Vehicle maximum mass (kg)", "example": 2000 }, "vehiclePowerKW": { "type": "number", "description": "Vehicle power in kW", "example": 110 }, "vehicleSeatsNumber": { "type": "number", "description": "Vehicle number of seats", "example": 5 }, "vehicleInsuranceCompany": { "type": "string", "description": "Insurance company (vehicle insurance or pedestrian health insurance)", "example": "State Farm" }, "vehicleInsurancePolicyNumber": { "type": "string", "description": "Insurance policy number (vehicle insurance or pedestrian health insurance)", "example": "POL-789012" }, "vehicleInsuranceCompany2": { "type": "string", "description": "Secondary insurance company (when the party carries two policies)", "example": "Allstate" }, "vehicleInsurancePolicyNumber2": { "type": "string", "description": "Secondary insurance policy number", "example": "POL-789012-B" }, "driverFirstName": { "type": "string", "description": "First name (driver for vehicles, person name for pedestrians)", "example": "Jane" }, "driverLastName": { "type": "string", "description": "Last name (driver for vehicles, person name for pedestrians)", "example": "Smith" }, "driverPhone": { "type": "string", "description": "Phone number (driver for vehicles, contact phone for pedestrians)", "example": "+1234567890" }, "driverEmail": { "type": "string", "description": "Email address (driver for vehicles, contact email for pedestrians)", "example": "jane.smith@example.com" }, "driverAddress": { "type": "string", "description": "Address (driver for vehicles, contact address for pedestrians)", "example": "456 Oak St, Los Angeles, CA 90001" }, "driverZipCode": { "type": "string", "description": "Zip code (driver for vehicles, contact zip for pedestrians)", "example": "90001" }, "driverCity": { "type": "string", "description": "City (driver for vehicles, contact city for pedestrians)", "example": "Los Angeles" }, "driverCountry": { "type": "string", "description": "Driver country", "example": "United States" }, "driverLicenceNumber": { "type": "string", "description": "Driver licence number", "example": "DL789012" }, "driverLicenceGroups": { "type": "array", "description": "Driver licence groups (can be array or comma-separated string)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "driverLicenceIssuedBy": { "type": "string", "description": "Driver licence issued by", "example": "DMV California" }, "driverLicenceValidFrom": { "type": "string", "description": "Driver licence valid from", "example": "2019-06-01", "format": "date-time" }, "driverLicenceValidTo": { "type": "string", "description": "Driver licence valid to", "example": "2029-06-01", "format": "date-time" }, "driverDob": { "type": "string", "description": "Driver date of birth", "example": "1985-03-20" }, "driverSignature": { "type": "string", "description": "Driver signature", "example": "data:image/png;base64,..." }, "driverLanguage": { "type": "string", "description": "Driver language", "example": "English" }, "ownerIsCompany": { "type": "boolean", "description": "Owner is company", "example": false }, "ownerCompanyName": { "type": "string", "description": "Owner company name", "example": "Acme Corp" }, "ownerFirstName": { "type": "string", "description": "Owner first name", "example": "Jane" }, "ownerLastName": { "type": "string", "description": "Owner last name", "example": "Smith" }, "ownerPhone": { "type": "string", "description": "Owner phone", "example": "+1234567890" }, "ownerEmail": { "type": "string", "description": "Owner email", "example": "jane.smith@example.com" }, "ownerAddress": { "type": "string", "description": "Owner address", "example": "456 Oak St, Los Angeles, CA 90001" }, "ownerZipCode": { "type": "string", "description": "Owner zip code", "example": "90001" }, "ownerCity": { "type": "string", "description": "Owner city", "example": "Los Angeles" }, "ownerCountry": { "type": "string", "description": "Owner country", "example": "USA" }, "initialPointOfImpact": { "type": "string", "description": "Initial point of impact", "example": "Rear bumper" }, "secondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "visibleDamage": { "type": "string", "description": "Visible damage", "example": "Rear bumper, tail lights" }, "circumstancesVehicleB": { "type": "array", "description": "EU circumstances that apply to this opponent (e.g. parked, overtaking)", "example": [ "parked", "changing_lanes" ], "items": { "type": "string" } }, "description": { "type": "string", "description": "Description (appearance, clothing, circumstances for pedestrians; type, location for obstacles; optional for vehicles)", "example": "Elderly woman in red coat crossing at intersection" }, "refusedStatement": { "type": "boolean", "description": "Whether this opponent was present but refused to provide a statement", "example": false }, "fledScene": { "type": "boolean", "description": "Whether the opposing party left the scene before they could be identified (hit-and-run). Marks a real-but-unidentifiable participant so it is excluded from signature requests (CW-1325).", "example": false }, "vehicleRegistrationData": { "type": "object", "description": "Optional vehicle registration data from certificate scan. If provided, owner information will be automatically populated from this data.", "additionalProperties": true } }, "required": [ "reportId", "type" ] }, "ReportOpponentDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the opponent", "example": "550e8400-e29b-41d4-a716-446655440000" }, "reportId": { "type": "string", "description": "The UUID of the accident report", "example": "550e8400-e29b-41d4-a716-446655440000" }, "report": { "description": "The accident report", "allOf": [ { "$ref": "#/components/schemas/ReportDto" } ] }, "type": { "type": "string", "description": "Type of opponent", "example": "vehicle", "enum": [ "vehicle", "pedestrian", "obstacle" ] }, "vehicleVin": { "type": "string", "description": "Vehicle VIN", "example": "5FNRL5H63DB123456" }, "vehicleManufacturer": { "type": "string", "description": "Vehicle manufacturer/make", "example": "Honda" }, "vehicleModel": { "type": "string", "description": "Vehicle model", "example": "Civic" }, "vehicleType": { "type": "string", "description": "Vehicle type", "example": "Sedan" }, "vehicleRegistrationNumber": { "type": "string", "description": "Vehicle registration/license plate", "example": "XYZ-5678" }, "vehicleColor": { "type": "string", "description": "Vehicle color", "example": "Red" }, "vehicleDisplacementCCM": { "type": "number", "description": "Vehicle displacement in CCM", "example": 1998 }, "vehicleFuelType": { "type": "string", "description": "Vehicle fuel type", "example": "Petrol" }, "vehicleMassInService": { "type": "number", "description": "Vehicle mass in service (kg)", "example": 1500 }, "vehicleMaxMass": { "type": "number", "description": "Vehicle maximum mass (kg)", "example": 2000 }, "vehiclePowerKW": { "type": "number", "description": "Vehicle power in kW", "example": 110 }, "vehicleSeatsNumber": { "type": "number", "description": "Vehicle number of seats", "example": 5 }, "vehicleInsuranceCompany": { "type": "string", "description": "Insurance company (vehicle insurance or pedestrian health/liability insurance)", "example": "State Farm" }, "vehicleInsurancePolicyNumber": { "type": "string", "description": "Insurance policy number (vehicle insurance or pedestrian health/liability insurance)", "example": "POL-789012" }, "vehicleInsuranceCompany2": { "type": "string", "description": "Secondary insurance company (when the party carries two policies)", "example": "Allstate" }, "vehicleInsurancePolicyNumber2": { "type": "string", "description": "Secondary insurance policy number", "example": "POL-789012-B" }, "driverFirstName": { "type": "string", "description": "First name (driver for vehicles, person name for pedestrians)", "example": "Jane" }, "driverLastName": { "type": "string", "description": "Last name (driver for vehicles, person name for pedestrians)", "example": "Smith" }, "driverPhone": { "type": "string", "description": "Phone number (driver for vehicles, contact phone for pedestrians)", "example": "+1234567890" }, "driverEmail": { "type": "string", "description": "Email address (driver for vehicles, contact email for pedestrians)", "example": "jane.smith@example.com" }, "driverAddress": { "type": "string", "description": "Address (driver for vehicles, contact address for pedestrians)", "example": "456 Oak St, Los Angeles, CA 90001" }, "driverZipCode": { "type": "string", "description": "Driver zip code", "example": "90001" }, "driverCity": { "type": "string", "description": "Driver city", "example": "Los Angeles" }, "driverCountry": { "type": "string", "description": "Driver country", "example": "United States" }, "driverLicenceNumber": { "type": "string", "description": "Driver licence number", "example": "DL789012" }, "driverLicenceGroups": { "type": "array", "description": "Driver licence groups", "example": [ "B", "BE" ], "items": { "type": "string" } }, "driverLicenceIssuedBy": { "type": "string", "description": "Driver licence issued by", "example": "DMV California" }, "driverLicenceValidFrom": { "type": "string", "description": "Driver licence valid from", "example": "2019-06-01", "format": "date-time" }, "driverLicenceValidTo": { "type": "string", "description": "Driver licence valid to", "example": "2029-06-01", "format": "date-time" }, "driverDob": { "type": "string", "description": "Driver date of birth", "example": "1985-03-20" }, "driverSignature": { "type": "string", "description": "Driver signature", "example": "data:image/png;base64,..." }, "driverLanguage": { "type": "string", "description": "Driver language", "example": "English" }, "ownerIsCompany": { "type": "boolean", "description": "Owner is company", "example": false }, "ownerCompanyName": { "type": "string", "description": "Owner company name", "example": "Acme Corp" }, "ownerFirstName": { "type": "string", "description": "Owner first name", "example": "Jane" }, "ownerLastName": { "type": "string", "description": "Owner last name", "example": "Smith" }, "ownerPhone": { "type": "string", "description": "Owner phone", "example": "+1234567890" }, "ownerEmail": { "type": "string", "description": "Owner email", "example": "jane.smith@example.com" }, "ownerAddress": { "type": "string", "description": "Owner address", "example": "456 Oak St, Los Angeles, CA 90001" }, "ownerZipCode": { "type": "string", "description": "Owner zip code", "example": "90001" }, "ownerCity": { "type": "string", "description": "Owner city", "example": "Los Angeles" }, "ownerCountry": { "type": "string", "description": "Owner country", "example": "USA" }, "initialPointOfImpact": { "type": "string", "description": "Initial point of impact", "example": "Rear bumper" }, "secondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "visibleDamage": { "type": "string", "description": "Visible damage", "example": "Rear bumper, tail lights" }, "circumstancesVehicleB": { "type": "array", "description": "EU circumstances that apply to this opponent (e.g. parked, overtaking)", "example": [ "parked", "changing_lanes" ], "items": { "type": "string" } }, "description": { "type": "string", "description": "Description (appearance, clothing, circumstances for pedestrians; type, location for obstacles; optional for vehicles)", "example": "Elderly woman in red coat crossing at intersection" }, "refusedStatement": { "type": "boolean", "description": "Whether this opponent was present but refused to provide a statement", "example": false }, "fledScene": { "type": "boolean", "description": "Whether the opposing party left the scene before they could be identified (hit-and-run). Such an opponent is a real participant but carries no contact/vehicle details, so it is excluded from signature requests and rendered with a \"left the scene\" note rather than as an empty card or an undefined obstacle (CW-1325).", "example": false }, "guestToken": { "type": "string", "description": "delegated access token for opponent to fill their own data", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "guestTokenExpiresAt": { "type": "string", "description": "Guest token expiration date", "example": "2024-01-08T00:00:00.000Z", "format": "date-time" }, "guestAccessStatus": { "type": "string", "description": "delegated access status", "example": "not_requested", "enum": [ "not_requested", "pending", "completed", "expired" ] }, "guestCompletedAt": { "type": "string", "description": "Date when the opponent completed filling their data", "example": "2024-01-05T00:00:00.000Z", "format": "date-time" }, "source": { "type": "string", "description": "Provenance of the row. crash_assistant_sync = auto-created by the mobile client mirroring AI-extracted crash-assistant data; such rows may be retracted when the user confirms no other party was involved (CW-1262). Null = manually created (or legacy client).", "example": "crash_assistant_sync", "enum": [ "crash_assistant_sync" ] }, "assistantIndex": { "type": "number", "description": "Position of this party in the crash-assistant session that produced the row (0-based). The assistant creates rows from two places — the QR/e-mail invite during the chat, the final sync at submit — and the client used to re-pair them with the session by list position, which mismatches as soon as the parties chose different methods (CW-1517). Null for rows not created from an assistant session (or legacy client).", "example": 2 }, "created": { "type": "string", "description": "The date when the record was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updated": { "type": "string", "description": "The date when the record was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deleted": { "type": "string", "description": "The date when the record was deleted (soft delete)", "example": null, "format": "date-time" } }, "required": [ "id", "reportId", "report", "type", "guestAccessStatus", "created", "updated" ] }, "UpdateReportOpponentDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of opponent", "example": "vehicle", "enum": [ "vehicle", "pedestrian", "obstacle" ] }, "assistantIndex": { "type": "number", "description": "Position of this party in the crash-assistant session (0-based). Send it from every assistant-driven create so a row can be re-paired with its party later; matching by list position mixes parties up as soon as they used different methods (CW-1517). Omit for manual creates.", "example": 2 }, "vehicleVin": { "type": "string", "description": "Vehicle VIN (for vehicle opponents only)", "example": "5FNRL5H63DB123456" }, "vehicleManufacturer": { "type": "string", "description": "Vehicle manufacturer/make (for vehicle opponents only)", "example": "Honda" }, "vehicleModel": { "type": "string", "description": "Vehicle model", "example": "Civic" }, "vehicleType": { "type": "string", "description": "Vehicle type", "example": "Sedan" }, "vehicleRegistrationNumber": { "type": "string", "description": "Vehicle registration/license plate", "example": "XYZ-5678" }, "vehicleColor": { "type": "string", "description": "Vehicle color", "example": "Red" }, "vehicleDisplacementCCM": { "type": "number", "description": "Vehicle displacement in CCM", "example": 1998 }, "vehicleFuelType": { "type": "string", "description": "Vehicle fuel type", "example": "Petrol" }, "vehicleMassInService": { "type": "number", "description": "Vehicle mass in service (kg)", "example": 1500 }, "vehicleMaxMass": { "type": "number", "description": "Vehicle maximum mass (kg)", "example": 2000 }, "vehiclePowerKW": { "type": "number", "description": "Vehicle power in kW", "example": 110 }, "vehicleSeatsNumber": { "type": "number", "description": "Vehicle number of seats", "example": 5 }, "vehicleInsuranceCompany": { "type": "string", "description": "Insurance company (vehicle insurance or pedestrian health insurance)", "example": "State Farm" }, "vehicleInsurancePolicyNumber": { "type": "string", "description": "Insurance policy number (vehicle insurance or pedestrian health insurance)", "example": "POL-789012" }, "vehicleInsuranceCompany2": { "type": "string", "description": "Secondary insurance company (when the party carries two policies)", "example": "Allstate" }, "vehicleInsurancePolicyNumber2": { "type": "string", "description": "Secondary insurance policy number", "example": "POL-789012-B" }, "driverFirstName": { "type": "string", "description": "First name (driver for vehicles, person name for pedestrians)", "example": "Jane" }, "driverLastName": { "type": "string", "description": "Last name (driver for vehicles, person name for pedestrians)", "example": "Smith" }, "driverPhone": { "type": "string", "description": "Phone number (driver for vehicles, contact phone for pedestrians)", "example": "+1234567890" }, "driverEmail": { "type": "string", "description": "Email address (driver for vehicles, contact email for pedestrians)", "example": "jane.smith@example.com" }, "driverAddress": { "type": "string", "description": "Address (driver for vehicles, contact address for pedestrians)", "example": "456 Oak St, Los Angeles, CA 90001" }, "driverZipCode": { "type": "string", "description": "Zip code (driver for vehicles, contact zip for pedestrians)", "example": "90001" }, "driverCity": { "type": "string", "description": "City (driver for vehicles, contact city for pedestrians)", "example": "Los Angeles" }, "driverCountry": { "type": "string", "description": "Driver country", "example": "United States" }, "driverLicenceNumber": { "type": "string", "description": "Driver licence number", "example": "DL789012" }, "driverLicenceGroups": { "type": "array", "description": "Driver licence groups (can be array or comma-separated string)", "example": [ "B", "BE" ], "items": { "type": "string" } }, "driverLicenceIssuedBy": { "type": "string", "description": "Driver licence issued by", "example": "DMV California" }, "driverLicenceValidFrom": { "type": "string", "description": "Driver licence valid from", "example": "2019-06-01", "format": "date-time" }, "driverLicenceValidTo": { "type": "string", "description": "Driver licence valid to", "example": "2029-06-01", "format": "date-time" }, "driverDob": { "type": "string", "description": "Driver date of birth", "example": "1985-03-20" }, "driverSignature": { "type": "string", "description": "Driver signature", "example": "data:image/png;base64,..." }, "driverLanguage": { "type": "string", "description": "Driver language", "example": "English" }, "ownerIsCompany": { "type": "boolean", "description": "Owner is company", "example": false }, "ownerCompanyName": { "type": "string", "description": "Owner company name", "example": "Acme Corp" }, "ownerFirstName": { "type": "string", "description": "Owner first name", "example": "Jane" }, "ownerLastName": { "type": "string", "description": "Owner last name", "example": "Smith" }, "ownerPhone": { "type": "string", "description": "Owner phone", "example": "+1234567890" }, "ownerEmail": { "type": "string", "description": "Owner email", "example": "jane.smith@example.com" }, "ownerAddress": { "type": "string", "description": "Owner address", "example": "456 Oak St, Los Angeles, CA 90001" }, "ownerZipCode": { "type": "string", "description": "Owner zip code", "example": "90001" }, "ownerCity": { "type": "string", "description": "Owner city", "example": "Los Angeles" }, "ownerCountry": { "type": "string", "description": "Owner country", "example": "USA" }, "initialPointOfImpact": { "type": "string", "description": "Initial point of impact", "example": "Rear bumper" }, "secondaryPointsOfImpact": { "type": "array", "description": "Further damaged zones besides the initial point of impact (snake_case DamageLocation values)", "example": [ "rear_right" ], "items": { "type": "string" } }, "visibleDamage": { "type": "string", "description": "Visible damage", "example": "Rear bumper, tail lights" }, "circumstancesVehicleB": { "type": "array", "description": "EU circumstances that apply to this opponent (e.g. parked, overtaking)", "example": [ "parked", "changing_lanes" ], "items": { "type": "string" } }, "description": { "type": "string", "description": "Description (appearance, clothing, circumstances for pedestrians; type, location for obstacles; optional for vehicles)", "example": "Elderly woman in red coat crossing at intersection" }, "refusedStatement": { "type": "boolean", "description": "Whether this opponent was present but refused to provide a statement", "example": false }, "fledScene": { "type": "boolean", "description": "Whether the opposing party left the scene before they could be identified (hit-and-run). Marks a real-but-unidentifiable participant so it is excluded from signature requests (CW-1325).", "example": false }, "vehicleRegistrationData": { "type": "object", "description": "Optional vehicle registration data from certificate scan. If provided, owner information will be automatically populated from this data.", "additionalProperties": true } } }, "CreateWitnessDto": { "type": "object", "properties": { "accidentReportId": { "type": "string", "description": "The UUID of the accident report", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Name of the witness", "example": "Jane Smith" }, "address": { "type": "string", "description": "Address of the witness", "example": "456 Oak St, Los Angeles, CA 90001" }, "zipCode": { "type": "string", "description": "Zip/postal code", "example": "10000" }, "city": { "type": "string", "description": "City", "example": "Zagreb" }, "country": { "type": "string", "description": "Country", "example": "Croatia" }, "phoneNumber": { "type": "string", "description": "Phone number of the witness", "example": "+1234567890" }, "alternativePhoneNumber": { "type": "string", "description": "Alternative phone number", "example": "+0987654321" }, "emailAddress": { "type": "string", "description": "Email address of the witness", "example": "jane.smith@example.com" }, "witnessLanguage": { "type": "string", "description": "Witness language", "example": "English" }, "statement": { "type": "string", "description": "Witness statement about the accident", "example": "I saw the car run a red light and collide with the other vehicle." } }, "required": [ "accidentReportId", "name" ] }, "WitnessDto": { "type": "object", "properties": { "id": { "type": "number", "description": "The unique identifier", "example": 1 }, "accident_report_id": { "type": "string", "description": "The UUID of the accident report", "example": "550e8400-e29b-41d4-a716-446655440000" }, "report": { "description": "The accident report", "allOf": [ { "$ref": "#/components/schemas/ReportDto" } ] }, "name": { "type": "string", "description": "Name of the witness", "example": "Jane Smith" }, "address": { "type": "string", "description": "Address of the witness", "example": "456 Oak St, Los Angeles, CA 90001" }, "zipCode": { "type": "string", "description": "Zip/postal code", "example": "10000" }, "city": { "type": "string", "description": "City", "example": "Zagreb" }, "country": { "type": "string", "description": "Country", "example": "Croatia" }, "phone_number": { "type": "string", "description": "Phone number of the witness", "example": "+1234567890" }, "alternative_phone_number": { "type": "string", "description": "Alternative phone number", "example": "+0987654321" }, "email_address": { "type": "string", "description": "Email address of the witness", "example": "jane.smith@example.com" }, "witnessLanguage": { "type": "string", "description": "Witness language", "example": "English" }, "statement": { "type": "string", "description": "Witness statement about the accident", "example": "I saw the car run a red light and collide with the other vehicle." }, "guestToken": { "type": "string", "description": "delegated access token for witness to fill their own data", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "guestTokenExpiresAt": { "type": "string", "description": "Guest token expiration date", "example": "2024-01-08T00:00:00.000Z", "format": "date-time" }, "guestAccessStatus": { "type": "string", "description": "delegated access status", "example": "not_requested", "enum": [ "not_requested", "pending", "completed", "expired" ] }, "guestCompletedAt": { "type": "string", "description": "Date when the witness completed filling their data", "example": "2024-01-05T00:00:00.000Z", "format": "date-time" }, "created": { "type": "string", "description": "The date when the record was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updated": { "type": "string", "description": "The date when the record was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deleted": { "type": "string", "description": "The date when the record was deleted (soft delete)", "example": null, "format": "date-time" } }, "required": [ "id", "accident_report_id", "report", "name", "guestAccessStatus", "created", "updated" ] }, "UpdateWitnessDto": { "type": "object", "properties": { "accidentReportId": { "type": "string", "description": "The UUID of the accident report", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Name of the witness", "example": "Jane Smith" }, "address": { "type": "string", "description": "Address of the witness", "example": "456 Oak St, Los Angeles, CA 90001" }, "zipCode": { "type": "string", "description": "Zip/postal code", "example": "10000" }, "city": { "type": "string", "description": "City", "example": "Zagreb" }, "country": { "type": "string", "description": "Country", "example": "Croatia" }, "phoneNumber": { "type": "string", "description": "Phone number of the witness", "example": "+1234567890" }, "alternativePhoneNumber": { "type": "string", "description": "Alternative phone number", "example": "+0987654321" }, "emailAddress": { "type": "string", "description": "Email address of the witness", "example": "jane.smith@example.com" }, "witnessLanguage": { "type": "string", "description": "Witness language", "example": "English" }, "statement": { "type": "string", "description": "Witness statement about the accident", "example": "I saw the car run a red light and collide with the other vehicle." } } }, "BoundingBoxDto": { "type": "object", "properties": { "north": { "type": "number", "description": "North latitude", "example": 48.209 }, "south": { "type": "number", "description": "South latitude", "example": 48.2074 }, "east": { "type": "number", "description": "East longitude", "example": 16.375 }, "west": { "type": "number", "description": "West longitude", "example": 16.3726 } }, "required": [ "north", "south", "east", "west" ] }, "GenerateSketchDto": { "type": "object", "properties": { "latitude": { "type": "number", "description": "Accident point latitude (WGS84). If omitted, uses the report location.", "example": 48.2082 }, "longitude": { "type": "number", "description": "Accident point longitude (WGS84). If omitted, uses the report location.", "example": 16.3738 }, "boundingBox": { "description": "Visible map area bounding box. If omitted, auto-calculated from coordinates + zoom level.", "allOf": [ { "$ref": "#/components/schemas/BoundingBoxDto" } ] }, "zoomLevel": { "type": "number", "description": "Map zoom level (affects bounding box size when auto-calculated)", "example": 17 }, "orientation": { "type": "number", "description": "Map rotation in degrees", "example": 0 }, "showStreetNames": { "type": "boolean", "description": "Overlay street names along road curves, positioned near the image edges", "example": false }, "showRoads": { "type": "boolean", "description": "Draw the yellow road polylines on top of the aerial imagery", "example": true }, "showRails": { "type": "boolean", "description": "Draw railway tracks (white base + dark cross-ties) on top of the aerial imagery", "example": true }, "showAerial": { "type": "boolean", "description": "Render the aerial satellite imagery as the base layer", "example": true } } }, "ArrowDto": { "type": "object", "properties": {} }, "AnnotationDto": { "type": "object", "properties": {} }, "UpdateSketchDto": { "type": "object", "properties": { "vehicles": { "description": "Vehicle placements", "type": "array", "items": { "$ref": "#/components/schemas/VehicleDto" } }, "arrows": { "description": "Arrow placements", "type": "array", "items": { "$ref": "#/components/schemas/ArrowDto" } }, "annotations": { "description": "Annotations (text, freehand)", "type": "array", "items": { "$ref": "#/components/schemas/AnnotationDto" } } } }, "CreateUploadDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the upload (optional, will be auto-generated if not provided)", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "The UUID of the organization this upload belongs to", "example": "550e8400-e29b-41d4-a716-446655440001" }, "userId": { "type": "string", "description": "The UUID of the user who uploaded this file", "example": "550e8400-e29b-41d4-a716-446655440002" }, "witnessId": { "type": "number", "description": "The ID of the witness who uploaded this file", "example": 1 }, "reportOpponentId": { "type": "string", "description": "The UUID of the report opponent who uploaded this file", "example": "550e8400-e29b-41d4-a716-446655440003" }, "caption": { "type": "string", "description": "Caption for the upload", "example": "Front bumper damage" }, "fileName": { "type": "string", "description": "The original file name", "example": "recording.m4a" }, "extension": { "type": "string", "description": "File extension", "example": "m4a" }, "contentType": { "type": "string", "description": "MIME content type", "example": "audio/mp4" }, "sizeBytes": { "type": "number", "description": "File size in bytes", "example": 1048576 }, "width": { "type": "number", "description": "Width in pixels (for images/videos)", "example": 1920 }, "height": { "type": "number", "description": "Height in pixels (for images/videos)", "example": 1080 }, "durationSeconds": { "type": "number", "description": "Duration in seconds (for audio/video)", "example": 120.5 }, "url": { "type": "string", "description": "URL to the uploaded file", "example": "https://files.crashwise.app/ORGA1234/uploads/file.m4a" }, "thumbnailUrl": { "type": "string", "description": "URL to the thumbnail image", "example": "https://files.crashwise.app/ORGA1234/thumbnails/file.jpg" }, "transcriptStatus": { "type": "string", "description": "Transcription status", "example": "N", "enum": [ "D", "N", "P", "E" ] }, "transcriptionJson": { "type": "object", "description": "Full transcription response JSON from the transcription service", "example": { "id": "25b30b7f-7bbd-49ec-9759-7275138b6496", "status": "completed", "text": "This is the transcribed text." }, "additionalProperties": true }, "transcriptionText": { "type": "string", "description": "Extracted transcription text", "example": "This is the transcribed text from the audio file." }, "metadata": { "type": "object", "description": "Additional metadata for the upload", "example": { "uploadedFrom": "mobile", "device": "iPhone 13" }, "additionalProperties": true } }, "required": [ "fileName", "extension", "contentType", "sizeBytes", "url" ] }, "UploadDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the upload", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "The UUID of the organization this upload belongs to", "example": "550e8400-e29b-41d4-a716-446655440001" }, "organization": { "description": "The organization this upload belongs to", "allOf": [ { "$ref": "#/components/schemas/OrganizationDto" } ] }, "userId": { "type": "string", "description": "The UUID of the user who uploaded this file", "example": "550e8400-e29b-41d4-a716-446655440002" }, "user": { "description": "The user who uploaded this file", "allOf": [ { "$ref": "#/components/schemas/UserDto" } ] }, "witnessId": { "type": "number", "description": "The ID of the witness who uploaded this file", "example": 1 }, "witness": { "description": "The witness who uploaded this file", "allOf": [ { "$ref": "#/components/schemas/WitnessDto" } ] }, "reportOpponentId": { "type": "string", "description": "The UUID of the report opponent who uploaded this file", "example": "550e8400-e29b-41d4-a716-446655440003" }, "reportOpponent": { "description": "The report opponent who uploaded this file", "allOf": [ { "$ref": "#/components/schemas/ReportOpponentDto" } ] }, "caption": { "type": "string", "description": "Caption for the upload", "example": "Front bumper damage" }, "fileName": { "type": "string", "description": "The original file name", "example": "recording.m4a" }, "extension": { "type": "string", "description": "File extension", "example": "m4a" }, "contentType": { "type": "string", "description": "MIME content type", "example": "audio/mp4" }, "sizeBytes": { "type": "number", "description": "File size in bytes", "example": 1048576 }, "width": { "type": "number", "description": "Width in pixels (for images/videos)", "example": 1920 }, "height": { "type": "number", "description": "Height in pixels (for images/videos)", "example": 1080 }, "durationSeconds": { "type": "number", "description": "Duration in seconds (for audio/video)", "example": 120.5 }, "url": { "type": "string", "description": "URL to the uploaded file", "example": "https://files.crashwise.app/ORGA1234/uploads/file.m4a" }, "thumbnailUrl": { "type": "string", "description": "URL to the thumbnail image", "example": "https://files.crashwise.app/ORGA1234/thumbnails/file.jpg" }, "transcriptStatus": { "type": "string", "description": "Transcription status", "example": "D", "enum": [ "D", "N", "P", "E" ] }, "transcriptionJson": { "type": "object", "description": "Full transcription response JSON from the transcription service", "example": { "id": "25b30b7f-7bbd-49ec-9759-7275138b6496", "status": "completed", "text": "This is the transcribed text." }, "additionalProperties": true }, "transcriptionText": { "type": "string", "description": "Extracted transcription text", "example": "This is the transcribed text from the audio file." }, "metadata": { "type": "object", "description": "Additional metadata for the upload", "example": { "uploadedFrom": "mobile", "device": "iPhone 13" }, "additionalProperties": true }, "validationStatus": { "type": "string", "description": "Background validation status of the photo", "example": "pending", "enum": [ "pending", "pass", "warning", "fail" ] }, "validationReason": { "type": "string", "description": "User-facing reason describing why the photo was flagged", "example": "This photo looks blurry" }, "validationIssues": { "type": "array", "description": "Array of issue codes (e.g. blurry, too_dark, off_subject)", "example": [ "blurry", "too_dark" ], "items": { "type": "string" } }, "validationRequestedSubject": { "type": "string", "description": "The subject the AI asked the user to photograph", "example": "close_up_own" }, "validationRetakeCount": { "type": "number", "description": "Number of times the user has retaken this photo", "example": 0 }, "validationValidatedAt": { "type": "string", "description": "When validation last completed", "format": "date-time" }, "validationSource": { "type": "string", "description": "Where the photo was captured from", "enum": [ "mobile", "guest_web" ] }, "validationUserDecision": { "type": "string", "description": "What the user chose on the review screen", "example": "pending", "enum": [ "pending", "skip", "accepted" ] }, "createdAt": { "type": "string", "description": "The date when the upload was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date when the upload was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deletedAt": { "type": "string", "description": "The date when the upload was deleted (soft delete)", "example": null, "format": "date-time" } }, "required": [ "id", "fileName", "extension", "contentType", "sizeBytes", "url", "transcriptStatus", "validationStatus", "validationRetakeCount", "validationUserDecision", "createdAt", "updatedAt" ] }, "UpdateUploadDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the upload (optional, will be auto-generated if not provided)", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "The UUID of the organization this upload belongs to", "example": "550e8400-e29b-41d4-a716-446655440001" }, "userId": { "type": "string", "description": "The UUID of the user who uploaded this file", "example": "550e8400-e29b-41d4-a716-446655440002" }, "witnessId": { "type": "number", "description": "The ID of the witness who uploaded this file", "example": 1 }, "reportOpponentId": { "type": "string", "description": "The UUID of the report opponent who uploaded this file", "example": "550e8400-e29b-41d4-a716-446655440003" }, "caption": { "type": "string", "description": "Caption for the upload", "example": "Front bumper damage" }, "fileName": { "type": "string", "description": "The original file name", "example": "recording.m4a" }, "extension": { "type": "string", "description": "File extension", "example": "m4a" }, "contentType": { "type": "string", "description": "MIME content type", "example": "audio/mp4" }, "sizeBytes": { "type": "number", "description": "File size in bytes", "example": 1048576 }, "width": { "type": "number", "description": "Width in pixels (for images/videos)", "example": 1920 }, "height": { "type": "number", "description": "Height in pixels (for images/videos)", "example": 1080 }, "durationSeconds": { "type": "number", "description": "Duration in seconds (for audio/video)", "example": 120.5 }, "url": { "type": "string", "description": "URL to the uploaded file", "example": "https://files.crashwise.app/ORGA1234/uploads/file.m4a" }, "thumbnailUrl": { "type": "string", "description": "URL to the thumbnail image", "example": "https://files.crashwise.app/ORGA1234/thumbnails/file.jpg" }, "transcriptStatus": { "type": "string", "description": "Transcription status", "example": "N", "enum": [ "D", "N", "P", "E" ] }, "transcriptionJson": { "type": "object", "description": "Full transcription response JSON from the transcription service", "example": { "id": "25b30b7f-7bbd-49ec-9759-7275138b6496", "status": "completed", "text": "This is the transcribed text." }, "additionalProperties": true }, "transcriptionText": { "type": "string", "description": "Extracted transcription text", "example": "This is the transcribed text from the audio file." }, "metadata": { "type": "object", "description": "Additional metadata for the upload", "example": { "uploadedFrom": "mobile", "device": "iPhone 13" }, "additionalProperties": true } } }, "CreateUserDto": { "type": "object", "properties": { "username": { "type": "string", "description": "The username of the user", "example": "john_doe" }, "email": { "type": "string", "description": "The email address of the user", "example": "john.doe@example.com" }, "password": { "type": "string", "description": "The password of the user", "example": "SecurePassword123!" }, "firstName": { "type": "string", "description": "The first name of the user", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the user", "example": "Doe" }, "phoneNumber": { "type": "string", "description": "The phone number of the user", "example": "+1234567890" }, "country": { "type": "string", "description": "The country of the user", "example": "United States" }, "timezone": { "type": "string", "description": "The timezone of the user", "example": "America/New_York" }, "address": { "type": "object", "description": "The address of the user", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "additionalProperties": true }, "role": { "type": "string", "description": "The role of the user", "example": "driver", "enum": [ "driver", "admin", "group-admin", "super-admin" ] }, "organizationId": { "type": "string", "description": "The UUID of the organization this user belongs to", "example": "550e8400-e29b-41d4-a716-446655440002" }, "additionalOrganizationIds": { "type": "array", "description": "For group admins only: additional organizations beyond the primary organizationId.", "items": { "type": "string" } }, "isVerified": { "type": "boolean", "description": "Whether the email is verified", "example": false }, "defaultVehicleId": { "type": "string", "description": "The default vehicle ID for the user", "example": "550e8400-e29b-41d4-a716-446655440001" }, "languageCode": { "type": "string", "description": "Language code", "example": "en" } }, "required": [ "username", "email", "password", "firstName", "lastName" ] }, "UserImportItemDto": { "type": "object", "properties": { "organizationId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440001" }, "email": { "type": "string", "example": "john.doe@example.com" }, "password": { "type": "string", "example": "SecurePassword123!" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "phoneNumber": { "type": "string", "example": "+1234567890" }, "vehicleRegistrationNumber": { "type": "string", "example": "W-94230G" }, "address": { "type": "object", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "additionalProperties": true }, "role": { "type": "string", "example": "driver", "enum": [ "driver", "admin", "group-admin", "super-admin" ] }, "isVerified": { "type": "boolean", "example": false }, "drivingLicenceNumber": { "type": "string", "example": "DL-123456789" }, "drivingLicenceType": { "type": "string", "example": "B" }, "drivingLicenceIssuer": { "type": "string", "example": "Department of Motor Vehicles" }, "drivingLicenceValidFrom": { "type": "string", "example": "2020-01-01" }, "drivingLicenceValidTo": { "type": "string", "example": "2030-01-01" } }, "required": [ "email", "firstName", "lastName" ] }, "ImportUsersDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Target organization for the whole batch. Applied to every row that does not carry its own organizationId. Required when a group-admin manages more than one organization.", "example": "550e8400-e29b-41d4-a716-446655440002" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserImportItemDto" } } }, "required": [ "users" ] }, "UpdateUserDto": { "type": "object", "properties": { "username": { "type": "string", "description": "The username of the user", "example": "john_doe" }, "email": { "type": "string", "description": "The email address of the user", "example": "john.doe@example.com" }, "firstName": { "type": "string", "description": "The first name of the user", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the user", "example": "Doe" }, "phoneNumber": { "type": "string", "description": "The phone number of the user", "example": "+1234567890" }, "country": { "type": "string", "description": "The country of the user", "example": "United States" }, "timezone": { "type": "string", "description": "The timezone of the user", "example": "America/New_York" }, "address": { "type": "object", "description": "The address of the user", "example": { "street": "123 Main St", "city": "New York", "zipcode": "10001", "country": "United States" }, "additionalProperties": true }, "role": { "type": "string", "description": "The role of the user", "example": "driver", "enum": [ "driver", "admin", "group-admin", "super-admin" ] }, "organizationId": { "type": "string", "description": "The UUID of the organization this user belongs to", "example": "550e8400-e29b-41d4-a716-446655440002" }, "additionalOrganizationIds": { "type": "array", "description": "For admins: the additional organizations to assign beyond the primary organizationId. Replaces the existing set. Super-requires elevated privileges.", "items": { "type": "string" } }, "isVerified": { "type": "boolean", "description": "Whether the email is verified", "example": false }, "defaultVehicleId": { "type": "string", "description": "The default vehicle ID for the user", "example": "550e8400-e29b-41d4-a716-446655440001" }, "languageCode": { "type": "string", "description": "Language code", "example": "en" } } }, "VehicleManufacturerDto": { "type": "object", "properties": { "id": { "type": "number", "description": "The unique identifier of the manufacturer", "example": 1 }, "uuid": { "type": "string", "description": "The UUID of the manufacturer", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Manufacturer name", "example": "Toyota" }, "normalized_name": { "type": "string", "description": "Normalized manufacturer name (uppercase)", "example": "TOYOTA" }, "created": { "type": "string", "description": "The date when the manufacturer was created", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "updated": { "type": "string", "description": "The date when the manufacturer was last updated", "example": "2024-01-01T00:00:00.000Z", "format": "date-time" }, "deleted": { "type": "string", "description": "The date when the manufacturer was deleted (soft delete)", "example": null, "format": "date-time" } }, "required": [ "id", "uuid", "name", "normalized_name", "created", "updated" ] }, "CreateVehicleDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The UUID of the organization", "example": "550e8400-e29b-41d4-a716-446655440001" }, "vin": { "type": "string", "description": "Vehicle Identification Number", "example": "1HGBH41JXMN109186" }, "manufacturer": { "type": "string", "description": "Vehicle manufacturer/make", "example": "Toyota" }, "model": { "type": "string", "description": "Vehicle model", "example": "Camry" }, "vehicleType": { "type": "string", "description": "Vehicle type", "example": "Sedan" }, "registrationNumber": { "type": "string", "description": "Vehicle registration/license plate number", "example": "ABC-1234" }, "internalVehicleNumber": { "type": "string", "description": "Fleet-internal vehicle number maintained by the customer. An empty string clears it, so the the web application and mobile forms can submit the untouched field without inventing a second \"no number\" value that would sort apart from the rows that never had one.", "example": "FZG-0042" }, "color": { "type": "string", "description": "Vehicle color", "example": "Blue" }, "displacementCCM": { "type": "number", "description": "Engine displacement in cubic centimeters (CCM)", "example": 1998 }, "fuelType": { "type": "string", "description": "Fuel type of the vehicle", "example": "Diesel" }, "massInService": { "type": "number", "description": "Mass in service (kg)", "example": 1500 }, "maxMass": { "type": "number", "description": "Maximum mass (kg)", "example": 2000 }, "powerKW": { "type": "number", "description": "Power in kilowatts (kW)", "example": 110 }, "seatsNumber": { "type": "number", "description": "Number of seats", "example": 5 }, "insuranceCompany": { "type": "string", "description": "Insurance company name", "example": "State Farm" }, "insurancePolicyNumber": { "type": "string", "description": "Insurance policy number", "example": "POL-123456" }, "insuredAddress": { "type": "string", "description": "Insured address", "example": "123 Main St" }, "insuredCompanyName": { "type": "string", "description": "Insured company name", "example": "ABC Corp" }, "insuredIsCompany": { "type": "boolean", "description": "Is the insured a company", "example": false }, "insuredFirstName": { "type": "string", "description": "Insured first name", "example": "John" }, "insuredLastName": { "type": "string", "description": "Insured last name", "example": "Doe" }, "insuredEmailAddress": { "type": "string", "description": "Insured email", "example": "john@example.com" }, "insuredPhoneNumber": { "type": "string", "description": "Insured phone", "example": "+1234567890" }, "insuredStreet": { "type": "string", "description": "Insured street", "example": "123 Main St" }, "insuredZipCode": { "type": "string", "description": "Insured zip code", "example": "10001" }, "insuredCity": { "type": "string", "description": "Insured city", "example": "New York" }, "insuredCountry": { "type": "string", "description": "Insured country", "example": "United States" }, "policyHolderFirstName": { "type": "string", "description": "Policy holder first name", "example": "Jane" }, "policyHolderLastName": { "type": "string", "description": "Policy holder last name", "example": "Smith" }, "policyHolderAddress": { "type": "string", "description": "Policy holder address", "example": "456 Oak Ave" }, "policyHolderCity": { "type": "string", "description": "Policy holder city", "example": "Los Angeles" }, "policyHolderCountry": { "type": "string", "description": "Policy holder country", "example": "United States" }, "policyHolderZip": { "type": "string", "description": "Policy holder zip code", "example": "90001" }, "policyHolderInsurance": { "type": "string", "description": "Policy holder insurance", "example": "State Farm" }, "insuranceCompany2": { "type": "string", "description": "Secondary insurance company", "example": "Allstate" }, "insurancePolicyNumber2": { "type": "string", "description": "Secondary insurance policy number", "example": "POL-789012" }, "insuredVatRecoverable": { "type": "boolean", "description": "Is VAT recoverable", "example": false }, "createdByUserId": { "type": "string", "description": "User ID who created this vehicle", "example": "550e8400-e29b-41d4-a716-446655440003" } }, "required": [ "organizationId", "manufacturer", "model", "vehicleType", "registrationNumber", "insuranceCompany", "insurancePolicyNumber", "createdByUserId" ] }, "VehicleImportItemDto": { "type": "object", "properties": { "organizationId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440001" }, "manufacturer": { "type": "string", "example": "Toyota" }, "model": { "type": "string", "example": "Camry" }, "vehicleType": { "type": "string", "example": "Sedan" }, "registrationNumber": { "type": "string", "example": "ABC-1234" }, "vin": { "type": "string", "example": "1HGBH41JXMN109186" }, "internalVehicleNumber": { "type": "string", "example": "FZG-0042" }, "displacementCCM": { "type": "number", "example": 1998 }, "fuelType": { "type": "string", "example": "Diesel" }, "massInService": { "type": "number", "example": 1500 }, "maxMass": { "type": "number", "example": 2000 }, "powerKW": { "type": "number", "example": 100 }, "seatsNumber": { "type": "number", "example": 5 }, "color": { "type": "string", "example": "Blue" }, "insuranceCompany": { "type": "string", "example": "State Farm" }, "insurancePolicyNumber": { "type": "string", "example": "POL-123456" }, "insuranceCompany2": { "type": "string", "example": "Allstate" }, "insurancePolicyNumber2": { "type": "string", "example": "POL-789012" }, "insuredIsCompany": { "type": "boolean", "example": false }, "insuredFirstName": { "type": "string", "example": "John" }, "insuredLastName": { "type": "string", "example": "Doe" }, "insuredCompanyName": { "type": "string", "example": "ABC Corp" }, "insuredStreet": { "type": "string", "example": "123 Main St" }, "insuredZipCode": { "type": "string", "example": "10001" }, "insuredCity": { "type": "string", "example": "New York" }, "insuredCountry": { "type": "string", "example": "United States" }, "insuredPhoneNumber": { "type": "string", "example": "+49 30 123456" }, "insuredEmailAddress": { "type": "string", "example": "john.doe@example.com" } }, "required": [ "manufacturer", "model", "vehicleType", "registrationNumber" ] }, "ImportVehiclesDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Target organization for the whole batch. Applied to every row that does not carry its own organizationId. Required when a group-admin manages more than one organization.", "example": "550e8400-e29b-41d4-a716-446655440002" }, "vehicles": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleImportItemDto" } } }, "required": [ "vehicles" ] }, "DeleteAllVehiclesDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The organization whose fleet is deleted", "example": "550e8400-e29b-41d4-a716-446655440001" }, "confirmation": { "type": "string", "description": "Must be the literal \"DELETE\". Re-checked here so a stray client call can never wipe a fleet without the user having typed it.", "example": "DELETE" } }, "required": [ "organizationId", "confirmation" ] }, "UpdateVehicleDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The UUID of the organization", "example": "550e8400-e29b-41d4-a716-446655440001" }, "vin": { "type": "string", "description": "Vehicle Identification Number", "example": "1HGBH41JXMN109186" }, "manufacturer": { "type": "string", "description": "Vehicle manufacturer/make", "example": "Toyota" }, "model": { "type": "string", "description": "Vehicle model", "example": "Camry" }, "vehicleType": { "type": "string", "description": "Vehicle type", "example": "Sedan" }, "registrationNumber": { "type": "string", "description": "Vehicle registration/license plate number", "example": "ABC-1234" }, "internalVehicleNumber": { "type": "string", "description": "Fleet-internal vehicle number maintained by the customer. An empty string clears it, so the the web application and mobile forms can submit the untouched field without inventing a second \"no number\" value that would sort apart from the rows that never had one.", "example": "FZG-0042" }, "color": { "type": "string", "description": "Vehicle color", "example": "Blue" }, "displacementCCM": { "type": "number", "description": "Engine displacement in cubic centimeters (CCM)", "example": 1998 }, "fuelType": { "type": "string", "description": "Fuel type of the vehicle", "example": "Diesel" }, "massInService": { "type": "number", "description": "Mass in service (kg)", "example": 1500 }, "maxMass": { "type": "number", "description": "Maximum mass (kg)", "example": 2000 }, "powerKW": { "type": "number", "description": "Power in kilowatts (kW)", "example": 110 }, "seatsNumber": { "type": "number", "description": "Number of seats", "example": 5 }, "insuranceCompany": { "type": "string", "description": "Insurance company name", "example": "State Farm" }, "insurancePolicyNumber": { "type": "string", "description": "Insurance policy number", "example": "POL-123456" }, "insuredAddress": { "type": "string", "description": "Insured address", "example": "123 Main St" }, "insuredCompanyName": { "type": "string", "description": "Insured company name", "example": "ABC Corp" }, "insuredIsCompany": { "type": "boolean", "description": "Is the insured a company", "example": false }, "insuredFirstName": { "type": "string", "description": "Insured first name", "example": "John" }, "insuredLastName": { "type": "string", "description": "Insured last name", "example": "Doe" }, "insuredEmailAddress": { "type": "string", "description": "Insured email", "example": "john@example.com" }, "insuredPhoneNumber": { "type": "string", "description": "Insured phone", "example": "+1234567890" }, "insuredStreet": { "type": "string", "description": "Insured street", "example": "123 Main St" }, "insuredZipCode": { "type": "string", "description": "Insured zip code", "example": "10001" }, "insuredCity": { "type": "string", "description": "Insured city", "example": "New York" }, "insuredCountry": { "type": "string", "description": "Insured country", "example": "United States" }, "policyHolderFirstName": { "type": "string", "description": "Policy holder first name", "example": "Jane" }, "policyHolderLastName": { "type": "string", "description": "Policy holder last name", "example": "Smith" }, "policyHolderAddress": { "type": "string", "description": "Policy holder address", "example": "456 Oak Ave" }, "policyHolderCity": { "type": "string", "description": "Policy holder city", "example": "Los Angeles" }, "policyHolderCountry": { "type": "string", "description": "Policy holder country", "example": "United States" }, "policyHolderZip": { "type": "string", "description": "Policy holder zip code", "example": "90001" }, "policyHolderInsurance": { "type": "string", "description": "Policy holder insurance", "example": "State Farm" }, "insuranceCompany2": { "type": "string", "description": "Secondary insurance company", "example": "Allstate" }, "insurancePolicyNumber2": { "type": "string", "description": "Secondary insurance policy number", "example": "POL-789012" }, "insuredVatRecoverable": { "type": "boolean", "description": "Is VAT recoverable", "example": false }, "createdByUserId": { "type": "string", "description": "User ID who created this vehicle", "example": "550e8400-e29b-41d4-a716-446655440003" } } } } } }