{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "x-addon-reason-codes": { "MISSING_STOCK_DEPENDENCY": "Select or upload an exact stock baseline before submitting A2L or tune.", "MISSING_A2L_DEPENDENCY": "A tuned contribution also requires an exact matching A2L.", "DEPENDENCY_NOT_ACCEPTED": "The selected dependency is not currently accepted and available.", "A2L_STOCK_MISMATCH": "The A2L must be verified against the same exact stock baseline as the tune.", "UNSUPPORTED_PROFILE": "A verification outcome: the family/layout is not qualified for the requested check; staff review is required.", "INCOMPLETE_A2L": "A verification outcome: parsing or required address-mapping evidence is incomplete; it does not establish a match.", "DUPLICATE_CONTRIBUTION": "A completed decision: equivalent content already exists; no second reward is issued.", "VERIFICATION_RETRYABLE": "The failed verification attempt must complete successfully before acceptance.", "QUOTE_EXPIRED": "Request a new price quote and ask the customer to confirm it before acquisition.", "QUOTE_ACCESS_CHANGED": "A free grant/staff quote no longer applies; refresh access and price before acquisition.", "INSUFFICIENT_CREDITS": "No debit occurred. Pending rewards are not spendable.", "CREDIT_ENTITLEMENT_REQUIRED": "Acquire this exact eligible version or obtain a valid manual grant.", "VERSION_WITHDRAWN": "This exact version is unavailable despite historical access records.", "DEPENDENCY_REVIEW_HOLD": "A required version needs review; new dependent acceptance/acquisition is blocked." }, "info": { "title": "Redline Autohaus Tuning API", "version": "1.2.0", "description": "Isolated tuning accounts, catalogue, immutable files, contribution verification, append-only credits and exact-version downloads. Isolated synthetic test Checkout and durable signed fulfillment are disabled by default; no live purchases, ECU flashing or generated tuning. Existing UDS APIs are independent. All examples are synthetic, except approved business contacts.", "contact": { "name": "Redline Autohaus & Performance", "url": "https://redlineautohaus.ca/contact", "email": "info@redlineautohaus.ca" } }, "servers": [ { "url": "https://api.redlineautohaus.com/api/v1/tuning", "description": "Production tuning API; separate from Next.js presentation." } ], "tags": [ { "name": "Authentication" }, { "name": "Account" }, { "name": "Files" }, { "name": "Reference data" }, { "name": "Software releases" }, { "name": "Administration" }, { "name": "Audit" }, { "name": "Site" }, { "name": "Contributions" }, { "name": "Credits" } ], "paths": { "/auth/register": { "post": { "operationId": "register", "summary": "Create a customer account", "description": "Requires bounded account/IP admission, then a fresh server-validated Turnstile register challenge before account, token or mail work. Always creates customer/pending_verification. Existing email produces the same generic202; passwords/hashes/internal IDs are never returned. Verification mail must be delivered through the configured transport.\n\nPermission: visitor (optional tuning session may personalize access). Approved Origin is required.", "tags": [ "Authentication" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "responses": { "202": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" }, "example": { "data": { "message": "If this address is eligible, email instructions will be sent." } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/register", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationRequest" }, "example": { "email": "customer@example.test", "password": "synthetic example passphrase", "displayName": "Example", "turnstileToken": "synthetic-turnstile-token" } } } } } }, "/auth/login": { "post": { "operationId": "login", "summary": "Sign in with a tuning account", "description": "Requires bounded account/IP admission, then a fresh server-validated Turnstile login challenge before credential or session work. Generic401 for incorrect email/password or suspended account. A correct unverified login can access account/verification screens, never customer bytes. Creates/rotates an opaque32-byte session cookie; never use localStorage.\n\nPermission: visitor (optional tuning session may personalize access). Approved Origin is required.", "tags": [ "Authentication" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "Set-Cookie": { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "API-host-only __Host-redline_tuning_session, Secure;HttpOnly;Path=/;SameSite=Lax. Browser JavaScript cannot read this header." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" }, "example": { "data": { "user": { "id": "11111111-1111-4111-8111-111111111111", "email": "customer@example.test", "displayName": "Example Customer", "companyName": null, "evcLicense": null, "phone": null, "role": "customer", "status": "active", "emailVerifiedAt": "2026-09-17T12:00:00.000Z", "lastLoginAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" }, "permissions": { "isStaff": false, "canManageCatalog": false, "canPublish": false, "canManageUsers": false, "canDownload": false }, "csrfToken": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "expiresAt": "2026-09-17T12:00:00.000Z" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/login", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "example": { "email": "customer@example.test", "password": "synthetic example passphrase", "turnstileToken": "synthetic-turnstile-token" } } } } } }, "/auth/session": { "get": { "operationId": "session", "summary": "Restore the current session", "description": "Returns stable session-bound CSRF and safe user/permissions. Concurrent tabs and ordinary reads do not rotate CSRF. Absolute/idle expiry is server enforced.\n\nPermission: customer or higher; staff access requires active verified account. ", "tags": [ "Authentication" ], "security": [ { "tuningSession": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" }, "example": { "data": { "user": { "id": "11111111-1111-4111-8111-111111111111", "email": "customer@example.test", "displayName": "Example Customer", "companyName": null, "evcLicense": null, "phone": null, "role": "customer", "status": "active", "emailVerifiedAt": "2026-09-17T12:00:00.000Z", "lastLoginAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" }, "permissions": { "isStaff": false, "canManageCatalog": false, "canPublish": false, "canManageUsers": false, "canDownload": false }, "csrfToken": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "expiresAt": "2026-09-17T12:00:00.000Z" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/session", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/session", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/session", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/session", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/session", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/auth/logout": { "post": { "operationId": "logout", "summary": "Revoke the current session", "description": "Idempotently revokes the current session and clears its API-host cookie. No request body or Content-Type required. Already absent/expired session can still clear the cookie.\n\nPermission: customer or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Authentication" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "204": { "description": "Completed without a response body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "Set-Cookie": { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Clears the API session cookie when the current session is revoked." } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/auth/logout-all": { "post": { "operationId": "logoutAll", "summary": "Revoke all own sessions", "description": "Revokes every own session and clears the cookie. No request body or Content-Type required.\n\nPermission: customer or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Authentication" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "204": { "description": "Completed without a response body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "Set-Cookie": { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Clears the API session cookie when the current session is revoked." } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/logout-all", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/auth/verify-email": { "post": { "operationId": "verifyEmail", "summary": "Consume an email verification link", "description": "Trusted-origin JSON POST consumes a hashed, single-use token, expires after24h. A GET never consumes it. Verification revokes existing sessions; sign in again.\n\nPermission: visitor (optional tuning session may personalize access). Approved Origin is required.", "tags": [ "Authentication" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailResponse" }, "example": { "data": { "message": "Email verified. Sign in to continue.", "returnTo": "/files" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/verify-email", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailRequest" }, "example": { "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } } } }, "/auth/resend-verification": { "post": { "operationId": "resendVerification", "summary": "Request another verification email", "description": "Generic response whether the address exists or is eligible. Issuing a replacement invalidates prior unused tokens of the same purpose. Shared account/IP throttling applies.\n\nPermission: visitor (optional tuning session may personalize access). Approved Origin is required.", "tags": [ "Authentication" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "responses": { "202": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendVerificationResponse" }, "example": { "data": { "message": "If this address is eligible, email instructions will be sent." } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/resend-verification", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" }, "example": { "email": "customer@example.test" } } } } } }, "/auth/forgot-password": { "post": { "operationId": "forgotPassword", "summary": "Request password recovery", "description": "Generic response whether the address exists or is eligible. Issuing a replacement invalidates prior unused tokens of the same purpose. Shared account/IP throttling applies.\n\nPermission: visitor (optional tuning session may personalize access). Approved Origin is required.", "tags": [ "Authentication" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "responses": { "202": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordResponse" }, "example": { "data": { "message": "If this address is eligible, email instructions will be sent." } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/forgot-password", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" }, "example": { "email": "customer@example.test" } } } } } }, "/auth/reset-password": { "post": { "operationId": "resetPassword", "summary": "Consume a password-reset token", "description": "Single-use hashed token expires after30minutes. Password replacement and all-session revocation are atomic. Does not automatically sign in.\n\nPermission: visitor (optional tuning session may personalize access). Approved Origin is required.", "tags": [ "Authentication" ], "security": [], "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "responses": { "204": { "description": "Completed without a response body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/auth/reset-password", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" }, "example": { "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "newPassword": "synthetic example passphrase" } } } } } }, "/admin/purchases/reconciliation": { "get": { "operationId": "purchaseReconciliationList", "summary": "Select a bounded purchase reconciliation page", "description": "Current active verified admin browser session only. Stable UUID cursor; at most20 summaries. Select an order for a bounded dry run. No domain writes or provider calls.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Files" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 } } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReconciliationListResponse" }, "example": { "data": [], "nextCursor": null } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/reconciliation", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/reconciliation", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/reconciliation", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/reconciliation", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/reconciliation", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" } }, "/admin/purchases/{orderId}/reconciliation": { "get": { "operationId": "purchaseReconciliation", "summary": "Dry-run local financial consistency and optional provider proof", "description": "No domain mutation. Bounded ledger/hold/receipt checks report incomplete scans and retained exceptions; no automatic repair. Optional configured test-provider GET proof is identified separately and rechecks authority/state after I/O. No raw provider objects, contact data or secrets returned. ETag hashes the financial snapshot, not an ordinary numeric row token.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Files" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "provider", "in": "query", "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[a-f0-9]{64}\"$", "example": "\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"" }, "description": "Financial snapshot precondition for a new resolution." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseReconciliationResponse" }, "example": { "data": { "orderId": "11111111-1111-4111-8111-111111111111", "paymentState": "Example", "recoveryState": "Example", "credits": "1", "netCredits": "1", "expectedNetCredits": "1", "wallet": { "balance": "1", "ledgerSum": "1", "restriction": "none", "purchaseHolds": 0, "complete": false }, "findings": [], "providerProof": "not_read", "receipts": [], "operations": [], "etag": "\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/reconciliation", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/reconciliation", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/reconciliation", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/reconciliation", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/reconciliation", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/reconciliation", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/reconciliation", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" } }, "/admin/purchases/{orderId}/resolutions": { "post": { "operationId": "resolvePurchase", "summary": "Run one permanently identified proof-driven staff resolution", "description": "Test/development only, disabled by default. Current admin, session, Origin and CSRF required; rechecked before permanent replay and financial commit. Body is only inboxId/reason: a retained terminal receipt UUID retries its facts; null records distinct operator order-probe provenance from stored locators. No client amounts, status or provider identities. Five permanent actions per target; three bounded crash executions each;120s lease. Same key never becomes a new action after24h. Network reads occur outside financial locks. Original signed receipt/facts/attempts stay intact. Only accepted proof and immutable compensation can change finance; inconsistent local sums refuse correction. Response completed means processed disposition, not necessarily paid. No provider writes.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[a-f0-9]{64}\"$", "example": "\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Permanent actor-scoped operation identity; never expires with the ordinary24h HTTP cache. Changed body conflicts forever." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvePurchaseResponse" }, "example": { "data": { "operationId": "11111111-1111-4111-8111-111111111111", "orderId": "11111111-1111-4111-8111-111111111111", "inboxId": "11111111-1111-4111-8111-111111111111", "source": "signed_receipt", "state": "processing", "executions": 1, "code": "Example" } } } } }, "202": { "description": "Same permanent operation is still processing; no new dispatch.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvePurchaseResponse" }, "example": { "data": { "operationId": "11111111-1111-4111-8111-111111111111", "orderId": "11111111-1111-4111-8111-111111111111", "inboxId": "11111111-1111-4111-8111-111111111111", "source": "signed_receipt", "state": "processing", "executions": 1, "code": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/purchases/11111111-1111-4111-8111-111111111111/resolutions", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseResolutionSelection" }, "example": { "inboxId": null, "reason": "Synthetic reconciliation review" } } } } } }, "/credits/packs": { "get": { "operationId": "checkoutPacks", "summary": "Read server-priced test credit packs", "description": "Disabled by default. Only explicitly enabled non-production test context and synthetic zero-tax catalogue are supported; no owner commercial policy or live activation is selected. Public DTO excludes merchant/customer/policy internals.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Files" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutPacksResponse" }, "example": { "data": { "purchaseEnabled": false, "catalogue": null } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/packs", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/packs", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/packs", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/credits/checkout": { "post": { "operationId": "createCheckout", "summary": "Create or reconcile own Checkout attempt", "description": "Browser session, trusted Origin, CSRF, current active verified account and unrestricted wallet required. Rate limited. Body accepts only pack key, catalogue revision and permanent local attempt identity. Server snapshots all pricing/URLs. Same attempt reuses its order; changed selection is 409. Ambiguous provider calls reconcile read-only and stay pending without a replacement. No credit grant occurs. Test-only; live and production calls are disabled.\n\nPermission: customer or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "credits": "1", "currency": "usd", "subtotalMinor": "1", "taxMinor": "1", "includedTaxMinor": null, "totalMinor": "1", "taxBehavior": "inclusive", "taxTreatment": "legacy", "approvedRecoveryPolicy": false, "paymentState": "created", "recoveryState": "none", "createdAt": "2026-09-17T12:00:00.000Z", "checkout": { "state": "pending", "url": "https://redlineautohaus.com/", "expiresAt": "2026-09-17T12:00:00.000Z" } } } } } }, "202": { "description": "Durable intent is pending creation or reconciliation; retry the same attempt, never manufacture a replacement.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "credits": "1", "currency": "usd", "subtotalMinor": "1", "taxMinor": "1", "includedTaxMinor": null, "totalMinor": "1", "taxBehavior": "inclusive", "taxTreatment": "legacy", "approvedRecoveryPolicy": false, "paymentState": "created", "recoveryState": "none", "createdAt": "2026-09-17T12:00:00.000Z", "checkout": { "state": "pending", "url": "https://redlineautohaus.com/", "expiresAt": "2026-09-17T12:00:00.000Z" } } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/credits/checkout", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSelection" }, "example": { "packKey": "synthetic-pack", "catalogueRevision": "synthetic-v1", "attemptKey": "synthetic-attempt" } } } } } }, "/me/purchases": { "get": { "operationId": "ownPurchases", "summary": "List own purchase history", "description": "Current account/session required. Owner-scoped bounded history; no provider identity or Checkout URLs. Payment fulfillment is separate from session creation and redirects.\n\nPermission: customer or higher; staff access requires active verified account. ", "tags": [ "Account" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnPurchasesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/me/purchases/{orderId}": { "get": { "operationId": "ownPurchase", "summary": "Read own purchase status", "description": "Owner-scoped local status; another account's ID is 404, including for staff. A currently open unexpired Checkout URL is returned only to its owner in the configured test context. This GET makes no provider calls. Pending status does not imply payment or credits.\n\nPermission: customer or higher; staff access requires active verified account. ", "tags": [ "Account" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnPurchaseResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "credits": "1", "currency": "usd", "subtotalMinor": "1", "taxMinor": "1", "includedTaxMinor": null, "totalMinor": "1", "taxBehavior": "inclusive", "taxTreatment": "legacy", "approvedRecoveryPolicy": false, "paymentState": "created", "recoveryState": "none", "createdAt": "2026-09-17T12:00:00.000Z", "checkout": { "state": "pending", "url": "https://redlineautohaus.com/", "expiresAt": "2026-09-17T12:00:00.000Z" } } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/purchases/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/me": { "get": { "operationId": "profile", "summary": "Read own profile", "description": "Sanitized own profile, role/status and verification state only.\n\nPermission: customer or higher; staff access requires active verified account. ", "tags": [ "Account" ], "security": [ { "tuningSession": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "email": "customer@example.test", "displayName": "Example Customer", "companyName": null, "evcLicense": null, "phone": null, "role": "customer", "status": "active", "emailVerifiedAt": "2026-09-17T12:00:00.000Z", "lastLoginAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" }, "patch": { "operationId": "updateProfile", "summary": "Edit own profile", "description": "Only displayName/companyName/EVC licence reference/phone. The EVC field accepts an official www.evc.de check link or official badge HTML and stores only a normalized public reference. Email changes and role assignment are not accepted.\n\nPermission: customer or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Account" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "email": "customer@example.test", "displayName": "Example Customer", "companyName": null, "evcLicense": null, "phone": null, "role": "customer", "status": "active", "emailVerifiedAt": "2026-09-17T12:00:00.000Z", "lastLoginAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfilePatch" }, "example": { "displayName": "Example Customer" } } } } } }, "/me/company-verification": { "get": { "operationId": "ownCompanyVerification", "summary": "Read own company verification summary", "description": "Browser session only. Returns the owner's configured company and effective verification, never staff evidence. ETag is shared with the account/profile row. An absent record is unverified.\n\nPermission: customer or higher; staff access requires active verified account. ", "tags": [ "Account" ], "security": [ { "tuningSession": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnCompanyVerificationResponse" }, "example": { "data": { "companyName": null, "status": "unverified", "companyVerified": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/company-verification", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/company-verification", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/company-verification", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/company-verification", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/company-verification", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/me/change-password": { "post": { "operationId": "changePassword", "summary": "Change own password", "description": "Checks current password, atomically replaces hash and revokes all own sessions/reset tokens. Fresh sign-in required.\n\nPermission: customer or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Account" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "204": { "description": "Completed without a response body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "Set-Cookie": { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Clears the API session cookie when the current session is revoked." } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/change-password", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" }, "example": { "currentPassword": "synthetic example passphrase", "newPassword": "synthetic example passphrase" } } } } } }, "/me/sessions": { "get": { "operationId": "sessions", "summary": "List own active sessions", "description": "Safe device/session IDs, expiry/last-seen and isCurrent. Token/IP/CSRF hashes never appear.\n\nPermission: customer or higher; staff access requires active verified account. ", "tags": [ "Account" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/me/sessions/{sessionId}": { "delete": { "operationId": "revokeSession", "summary": "Revoke one own session", "description": "A session owned by another account returns404. Current-session revocation clears the cookie. No request body or Content-Type required.\n\nPermission: customer or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Account" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "204": { "description": "Completed without a response body.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "Set-Cookie": { "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Clears the API session cookie when the current session is revoked." } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/sessions/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer" } }, "/me/downloads": { "get": { "operationId": "myDownloads", "summary": "List own download history", "description": "History includes transfer outcomes. Hidden/archived catalogue details are filtered from customer results. completed means API response finished, not proof of disk save.\n\nPermission: customer or higher; staff access requires active verified account. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Account" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyDownloadsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/downloads", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/downloads", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/downloads", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/downloads", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/downloads", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer", "x-api-key-permission": "tuning:read" } }, "/me/grants": { "get": { "operationId": "myGrants", "summary": "List own manual grants", "description": "Computes effective status/access with file visibility. Grant existence never overrides archive/staff-only policy; unavailable private records are omitted.\n\nPermission: customer or higher; staff access requires active verified account. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Account" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyGrantsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/grants", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/grants", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/grants", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/grants", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/me/grants", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer", "x-api-key-permission": "tuning:read" } }, "/site": { "get": { "operationId": "site", "summary": "Read public brand/contact settings", "description": "Approved parent contacts and upload capability limits only; purchaseEnabled is alwaysfalse. No environment variables or server secrets.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Site" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteResponse" }, "example": { "data": { "id": 1, "branchName": "Redline Autohaus Tuning", "parentName": "Redline Autohaus & Performance", "parentUrl": "https://redlineautohaus.ca/", "publicEmail": "info@redlineautohaus.ca", "phoneDisplay": "+1 519 997 2356", "phoneE164": "+15199972356", "addressLine1": "3086 Jefferson Blvd", "city": "Windsor", "region": "Ontario", "postalCode": "N8T 3G9", "countryCode": "CA", "timezone": "America/Toronto", "openingHours": { "monday": { "open": "08:00", "close": "18:00" }, "tuesday": { "open": "08:00", "close": "18:00" }, "wednesday": { "open": "08:00", "close": "18:00" }, "thursday": { "open": "08:00", "close": "18:00" }, "friday": { "open": "08:00", "close": "18:00" }, "saturday": null, "sunday": null }, "identityStatement": "RedlineAutohaus.com is the tuning branch of Redline Autohaus & Performance.", "contactSourceUrl": "https://redlineautohaus.ca/contact", "contactsVerifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "purchaseEnabled": false, "uploadLimits": { "maxBinBytes": 67108864, "maxA2lBytes": 67108864, "maxDocumentBytes": 10485760, "maxMultipartBytes": 68157440, "maxMetadataBytes": 65536 } } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/site", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/site", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/site", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/catalog/vehicle-makes": { "get": { "operationId": "listPublicVehicleMakes", "summary": "List available vehicle-makes", "description": "Only active reference records represented in published public inventory; vehicle relevance comes from verified fitments. No unused/draft inventory leaks.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Reference data" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicVehicleMakesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-makes", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-makes", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-makes", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/admin/catalog/vehicle-makes": { "get": { "operationId": "listAdminVehicleMakes", "summary": "Manage vehicle-makes", "description": "Includes unused/inactive records. Deactivate instead of deleting referenced catalogue history.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminVehicleMakesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "createVehicleMake", "summary": "Create vehicle-makes", "description": "Creates a typed reference record. Parent UUID and uniqueness are enforced. No inventory/compatibility claims are inferred.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVehicleMakeResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleMakeCreate" }, "example": { "name": "Example", "slug": "Example" } } } } } }, "/admin/catalog/vehicle-makes/{id}": { "get": { "operationId": "getVehicleMake", "summary": "Read one vehicle-makes", "description": "Current mutable reference record and its own ETag.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVehicleMakeResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateVehicleMake", "summary": "Update vehicle-makes", "description": "Validates field lengths, parent relationships and year ordering. ECU identity referenced by locked provenance cannot silently change.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVehicleMakeResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-makes/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleMakePatch" }, "example": { "name": "Example" } } } } } }, "/catalog/vehicle-models": { "get": { "operationId": "listPublicVehicleModels", "summary": "List available vehicle-models", "description": "Only active reference records represented in published public inventory; vehicle relevance comes from verified fitments. No unused/draft inventory leaks.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Reference data" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." }, { "name": "makeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Dependent parent selector." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicVehicleModelsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-models", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-models", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-models", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/admin/catalog/vehicle-models": { "get": { "operationId": "listAdminVehicleModels", "summary": "Manage vehicle-models", "description": "Includes unused/inactive records. Deactivate instead of deleting referenced catalogue history.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." }, { "name": "makeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Dependent parent selector." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminVehicleModelsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "createVehicleModel", "summary": "Create vehicle-models", "description": "Creates a typed reference record. Parent UUID and uniqueness are enforced. No inventory/compatibility claims are inferred.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVehicleModelResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "makeId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleModelCreate" }, "example": { "makeId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example" } } } } } }, "/admin/catalog/vehicle-models/{id}": { "get": { "operationId": "getVehicleModel", "summary": "Read one vehicle-models", "description": "Current mutable reference record and its own ETag.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVehicleModelResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "makeId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateVehicleModel", "summary": "Update vehicle-models", "description": "Validates field lengths, parent relationships and year ordering. ECU identity referenced by locked provenance cannot silently change.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVehicleModelResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "makeId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-models/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleModelPatch" }, "example": { "makeId": "11111111-1111-4111-8111-111111111111" } } } } } }, "/catalog/vehicle-variants": { "get": { "operationId": "listPublicVehicleVariants", "summary": "List available vehicle-variants", "description": "Only active reference records represented in published public inventory; vehicle relevance comes from verified fitments. No unused/draft inventory leaks.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Reference data" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." }, { "name": "modelId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Dependent parent selector." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1886, "maximum": 2200 }, "description": "Known inclusive variant years." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicVehicleVariantsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-variants", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-variants", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/vehicle-variants", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/admin/catalog/vehicle-variants": { "get": { "operationId": "listAdminVehicleVariants", "summary": "Manage vehicle-variants", "description": "Includes unused/inactive records. Deactivate instead of deleting referenced catalogue history.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." }, { "name": "modelId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Dependent parent selector." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1886, "maximum": 2200 }, "description": "Known inclusive variant years." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminVehicleVariantsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "createVehicleVariant", "summary": "Create vehicle-variants", "description": "Creates a typed reference record. Parent UUID and uniqueness are enforced. No inventory/compatibility claims are inferred.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVehicleVariantResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "modelId": "11111111-1111-4111-8111-111111111111", "variantKey": "Example", "name": "Example", "generation": "Example", "engineCode": "Example", "fuelType": "Example", "transmission": "Example", "displacementCc": 0, "powerKw": "150.00", "yearFrom": 1886, "yearTo": 1886, "market": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleVariantCreate" }, "example": { "modelId": "11111111-1111-4111-8111-111111111111", "variantKey": "Example", "name": "Example" } } } } } }, "/admin/catalog/vehicle-variants/{id}": { "get": { "operationId": "getVehicleVariant", "summary": "Read one vehicle-variants", "description": "Current mutable reference record and its own ETag.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetVehicleVariantResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "modelId": "11111111-1111-4111-8111-111111111111", "variantKey": "Example", "name": "Example", "generation": "Example", "engineCode": "Example", "fuelType": "Example", "transmission": "Example", "displacementCc": 0, "powerKw": "150.00", "yearFrom": 1886, "yearTo": 1886, "market": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateVehicleVariant", "summary": "Update vehicle-variants", "description": "Validates field lengths, parent relationships and year ordering. ECU identity referenced by locked provenance cannot silently change.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVehicleVariantResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "modelId": "11111111-1111-4111-8111-111111111111", "variantKey": "Example", "name": "Example", "generation": "Example", "engineCode": "Example", "fuelType": "Example", "transmission": "Example", "displacementCc": 0, "powerKw": "150.00", "yearFrom": 1886, "yearTo": 1886, "market": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/vehicle-variants/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleVariantPatch" }, "example": { "modelId": "11111111-1111-4111-8111-111111111111" } } } } } }, "/catalog/ecu-manufacturers": { "get": { "operationId": "listPublicEcuManufacturers", "summary": "List available ecu-manufacturers", "description": "Only active reference records represented in published public inventory; vehicle relevance comes from verified fitments. No unused/draft inventory leaks.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Reference data" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicEcuManufacturersResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/ecu-manufacturers", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/ecu-manufacturers", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/ecu-manufacturers", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/admin/catalog/ecu-manufacturers": { "get": { "operationId": "listAdminEcuManufacturers", "summary": "Manage ecu-manufacturers", "description": "Includes unused/inactive records. Deactivate instead of deleting referenced catalogue history.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminEcuManufacturersResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "createEcuManufacturer", "summary": "Create ecu-manufacturers", "description": "Creates a typed reference record. Parent UUID and uniqueness are enforced. No inventory/compatibility claims are inferred.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEcuManufacturerResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcuManufacturerCreate" }, "example": { "name": "Example", "slug": "Example" } } } } } }, "/admin/catalog/ecu-manufacturers/{id}": { "get": { "operationId": "getEcuManufacturer", "summary": "Read one ecu-manufacturers", "description": "Current mutable reference record and its own ETag.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEcuManufacturerResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateEcuManufacturer", "summary": "Update ecu-manufacturers", "description": "Validates field lengths, parent relationships and year ordering. ECU identity referenced by locked provenance cannot silently change.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEcuManufacturerResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-manufacturers/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcuManufacturerPatch" }, "example": { "name": "Example" } } } } } }, "/catalog/ecu-types": { "get": { "operationId": "listPublicEcuTypes", "summary": "List available ecu-types", "description": "Only active reference records represented in published public inventory; vehicle relevance comes from verified fitments. No unused/draft inventory leaks.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Reference data" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." }, { "name": "manufacturerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Dependent parent selector." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicEcuTypesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/ecu-types", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/ecu-types", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/catalog/ecu-types", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/admin/catalog/ecu-types": { "get": { "operationId": "listAdminEcuTypes", "summary": "Manage ecu-types", "description": "Includes unused/inactive records. Deactivate instead of deleting referenced catalogue history.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded reference-name search." }, { "name": "manufacturerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Dependent parent selector." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAdminEcuTypesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "createEcuType", "summary": "Create ecu-types", "description": "Creates a typed reference record. Parent UUID and uniqueness are enforced. No inventory/compatibility claims are inferred.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEcuTypeResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "manufacturerId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "family": "Example", "processor": "Example", "controllerRole": "engine", "notes": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcuTypeCreate" }, "example": { "manufacturerId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example" } } } } } }, "/admin/catalog/ecu-types/{id}": { "get": { "operationId": "getEcuType", "summary": "Read one ecu-types", "description": "Current mutable reference record and its own ETag.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Reference data" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEcuTypeResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "manufacturerId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "family": "Example", "processor": "Example", "controllerRole": "engine", "notes": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateEcuType", "summary": "Update ecu-types", "description": "Validates field lengths, parent relationships and year ordering. ECU identity referenced by locked provenance cannot silently change.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Reference data" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEcuTypeResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "manufacturerId": "11111111-1111-4111-8111-111111111111", "name": "Example", "slug": "Example", "family": "Example", "processor": "Example", "controllerRole": "engine", "notes": "Example", "isActive": false, "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/catalog/ecu-types/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EcuTypePatch" }, "example": { "manufacturerId": "11111111-1111-4111-8111-111111111111" } } } } } }, "/files": { "get": { "operationId": "files", "summary": "Explore published files", "description": "Metadata-only catalogue. All filters are ANDed. Current published version only; no blob bytes loaded. Optional account context computes advisory access; download rechecks it.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Files" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Search public titles/reference labels and any public identifier or AI vehicle/ECU metadata. Identifier lookup is case-insensitive and ignores separators, supporting full values and prefixes; SQL wildcards are escaped." }, { "name": "identifier", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Exact identifier across accepted AI/extractor results, supplements and verified releases. Lookup ignores case and separators; leading and trailing zeroes remain significant. Displayed values retain original punctuation." }, { "name": "identifierKind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "description": "Restrict exact match to an identifier kind." }, { "name": "identifierNamespace", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Manufacturer/system identifier naming scheme." }, { "name": "softwareReleaseId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "ecuManufacturerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "ecuTypeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "makeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "modelId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "vehicleVariantId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1886, "maximum": 2200 }, "description": "Includes variants with a known inclusive year range." }, { "name": "make", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "ecu", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "ecuMaker", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "modelYear", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] }, "description": "File artifact category." }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": "Uploader-defined public type (stage1, stage2, custom_stage3, unlocked); staff queries retain original version stage." }, { "name": "accessPolicy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "members", "manual_grant", "paid_coming_soon", "staff_only", "credits" ] }, "description": "Listing policy; visible locked listings remain searchable." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "updated", "title", "size", "published" ] }, "description": "Default relevance when searching, otherwise updated. Title ascending; size and dates descending; UUID stable secondary sort." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/files/facets": { "get": { "operationId": "fileFacets", "summary": "Count visible filter values", "description": "Distinct public file counts. Choice facets omit their own filter (and dependent vehicle filters) so another value remains selectable; other filters remain ANDed. Multiple fitments do not inflate counts. Identity candidates remain candidates, not verified fitment. Locked/coming-soon public listings count; private/draft/archive never do.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Files" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Search public titles/reference labels and any public identifier or AI vehicle/ECU metadata. Identifier lookup is case-insensitive and ignores separators, supporting full values and prefixes; SQL wildcards are escaped." }, { "name": "identifier", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Exact identifier across accepted AI/extractor results, supplements and verified releases. Lookup ignores case and separators; leading and trailing zeroes remain significant. Displayed values retain original punctuation." }, { "name": "identifierKind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "description": "Restrict exact match to an identifier kind." }, { "name": "identifierNamespace", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Manufacturer/system identifier naming scheme." }, { "name": "softwareReleaseId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "ecuManufacturerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "ecuTypeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "makeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "modelId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "vehicleVariantId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1886, "maximum": 2200 }, "description": "Includes variants with a known inclusive year range." }, { "name": "make", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "ecu", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "ecuMaker", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "modelYear", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] }, "description": "File artifact category." }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": "Uploader-defined public type (stage1, stage2, custom_stage3, unlocked); staff queries retain original version stage." }, { "name": "accessPolicy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "members", "manual_grant", "paid_coming_soon", "staff_only", "credits" ] }, "description": "Listing policy; visible locked listings remain searchable." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "updated", "title", "size", "published" ] }, "description": "Default relevance when searching, otherwise updated. Title ascending; size and dates descending; UUID stable secondary sort." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileFacetsResponse" }, "example": { "data": { "kind": [], "stage": [], "accessPolicy": [], "ecuManufacturerId": [], "ecuTypeId": [], "makeId": [], "modelId": [], "vehicleVariantId": [], "year": [], "make": [], "model": [], "ecu": [], "ecuMaker": [], "engine": [], "platform": [], "modelYear": [] } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/facets", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/facets", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/facets", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/files/{fileId}": { "get": { "operationId": "file", "summary": "Read a public file detail", "description": "Current published artifact, safe extracted identifiers/verified fitments and access decision. Optional version.companyAttribution contains a company name and independent Redline verification state for a proven uploader of the visible version; it may also contain official EVC/WinOLS check and image URLs supplied by that company. The attribution is omitted for absent company or unresolved provenance. Names are untrusted plain text. An EVC reference does not verify the company or certify a file, tune, ECU match or safety. HTTP ETag hashes this representation, including company and access, and supports If-None-Match/304. The body etag remains the file row edit token. Accepts UUID or a canonical/legacy slug ending in that UUID; catalogueIdentity.canonicalSlug is the current SEO location. Non-public records return404. Exact hidden baseline IDs/titles are omitted; use visibility-scoped /related.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Files" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 36, "maxLength": 8192, "description": "File UUID or public slug ending in the exact file UUID." }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "in": "header", "name": "If-None-Match", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "description": "Weak representation validator; not a staff If-Match edit token.", "schema": { "type": "string", "pattern": "^W/\"file-[0-9a-f]{64}\"$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "title": "Example", "description": "Example", "publicationState": "draft", "catalogueVisibility": "public", "accessPolicy": "members", "publishedVersionId": "11111111-1111-4111-8111-111111111111", "plannedPriceMinor": "8388608", "currency": "CAD", "publishedAt": "2026-09-17T12:00:00.000Z", "archivedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [] }, "access": { "canDownload": false, "reason": "PURCHASE_NOT_AVAILABLE" } } } } } }, "304": { "description": "The authorized current representation is unchanged; no response body." }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/files/{fileId}/related": { "get": { "operationId": "relatedFiles", "summary": "Read exact visible associations", "description": "Visibility-scoped baseline/A2L/document links retain exact versionId/versionLabel/isCurrentPublished. Never substitute a newer revision. Candidates are labelled; historic customer bytes remain unavailable.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Files" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 36, "maxLength": 8192, "description": "File UUID or public slug ending in the exact file UUID." }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedFilesResponse" }, "example": { "data": [] } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/related", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/related", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/related", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/related", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/files/{fileId}/download": { "get": { "operationId": "downloadFile", "summary": "Download current authorized bytes", "description": "Requires active verified user, public published file/current valid bytes and members policy or active manual grant. Staff-only overrides grants; paid_coming_soon needs a grant. Archive revokes access immediately.403 codes include EMAIL_VERIFICATION_REQUIRED,ACCESS_REQUIRED,PURCHASE_NOT_AVAILABLE,FILE_UNAVAILABLE.\n\nPermission: customer or higher; staff access requires active verified account. Alternatively use a Redline API key with tuning:download. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Files" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Exact authorized stored bytes; complete 200 response. HEAD returns405 with Allow:GET. No Range/resume support. Completion means the API finished sending, not proof of saving.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "Content-Disposition": { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "Sanitized attachment filename plus UTF-8 filename*." }, "Content-Length": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Exact stored byte count." }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Redline-DME-Role": { "description": "Optional allowlisted DME side for this exact authorized version; no sibling or set identity.", "schema": { "type": "string", "enum": [ "single", "master", "slave" ] } }, "X-Redline-File-Role": { "description": "Optional allowlisted role for this exact authorized version.", "schema": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } }, "text/plain": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } }, "text/markdown": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/download", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/download", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/download", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/download", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/download", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/download", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/files/11111111-1111-4111-8111-111111111111/download", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "customer", "x-api-key-permission": "tuning:download" } }, "/software-releases": { "get": { "operationId": "softwareReleases", "summary": "Find public software releases", "description": "Only releases represented by current public published verified links. A raw software number is not globally unique; results retain ECU/calibration/hardware context.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Software releases" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Release label/identifier search." }, { "name": "identifier", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Exact normalized identifier; duplicates across releases are valid." }, { "name": "identifierKind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "description": "Identifier category." }, { "name": "ecuTypeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Restrict to an ECU type." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoftwareReleasesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/software-releases", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/software-releases", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/software-releases", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/software-releases/{releaseId}": { "get": { "operationId": "softwareRelease", "summary": "Read public release and files", "description": "Safe identifiers, ECU and verified fitments, plus paginated current public files.404 if no public inventory represents this release.\n\nPermission: visitor (optional tuning session may personalize access). ", "tags": [ "Software releases" ], "security": [ {}, { "tuningSession": [] } ], "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoftwareReleaseResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "ecuTypeId": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "identificationStatus": "unverified", "verifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "ecu": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "family": "Example", "manufacturer": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example" } }, "identifiers": [], "fitments": [], "files": [], "filesPage": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/software-releases/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/software-releases/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/software-releases/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/software-releases/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "public" } }, "/admin/software-releases": { "get": { "operationId": "adminSoftwareReleases", "summary": "Manage software releases", "description": "Includes unverified/unused releases and internal verification evidence.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Software releases" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Release label/identifier search." }, { "name": "identifier", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Exact normalized identifier; duplicates across releases are valid." }, { "name": "identifierKind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "description": "Identifier category." }, { "name": "ecuTypeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Restrict to an ECU type." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSoftwareReleasesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "createSoftwareRelease", "summary": "Create a software release", "description": "Creates UUID release identity and bounded typed identifiers; no global uniqueness on raw software IDs. Marking verified requires recorded evidence.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Software releases" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSoftwareReleaseResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "ecuTypeId": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "identificationStatus": "unverified", "verifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "ecu": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "family": "Example", "manufacturer": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example" } }, "identifiers": [], "fitments": [], "createdBy": "11111111-1111-4111-8111-111111111111", "verifiedBy": "11111111-1111-4111-8111-111111111111", "verificationNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoftwareReleaseCreate" }, "example": { "ecuTypeId": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "identifiers": [] } } } } } }, "/admin/software-releases/{releaseId}": { "get": { "operationId": "adminSoftwareRelease", "summary": "Read staff release detail", "description": "Includes candidate fitments, source notes and verification metadata.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Software releases" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSoftwareReleaseResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "ecuTypeId": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "identificationStatus": "unverified", "verifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "ecu": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "family": "Example", "manufacturer": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example" } }, "identifiers": [], "fitments": [], "createdBy": "11111111-1111-4111-8111-111111111111", "verifiedBy": "11111111-1111-4111-8111-111111111111", "verificationNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateSoftwareRelease", "summary": "Update release metadata", "description": "Freeze identity-defining ECU/status/verification data after any version is locked. Display wording can change; material correction requires a new release/version.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Software releases" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSoftwareReleaseResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "ecuTypeId": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "identificationStatus": "unverified", "verifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "ecu": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "family": "Example", "manufacturer": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example" } }, "identifiers": [], "fitments": [], "createdBy": "11111111-1111-4111-8111-111111111111", "verifiedBy": "11111111-1111-4111-8111-111111111111", "verificationNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SoftwareReleasePatch" }, "example": { "displayName": "Synthetic release display label" } } } } } }, "/admin/software-releases/{releaseId}/identifiers": { "put": { "operationId": "replaceIdentifiers", "summary": "Replace release identifiers", "description": "Bounded replacement under release lock; at most one primary per kind. Preserve raw leading zeros/punctuation and case unless scheme known insensitive. Locked identity cannot change.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Software releases" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceIdentifiersResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "ecuTypeId": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "identificationStatus": "unverified", "verifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "ecu": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "family": "Example", "manufacturer": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example" } }, "identifiers": [], "fitments": [], "createdBy": "11111111-1111-4111-8111-111111111111", "verifiedBy": "11111111-1111-4111-8111-111111111111", "verificationNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/identifiers", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifiersReplacement" }, "example": { "identifiers": [] } } } } } }, "/admin/software-releases/{releaseId}/vehicle-fitments": { "put": { "operationId": "replaceFitments", "summary": "Replace vehicle fitment evidence", "description": "Verified fitments require evidence. Changes affecting published inventory require admin review; they never imply universal ECU flash compatibility.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Software releases" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "releaseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceFitmentsResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "ecuTypeId": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "identificationStatus": "unverified", "verifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "ecu": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "family": "Example", "manufacturer": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example" } }, "identifiers": [], "fitments": [], "createdBy": "11111111-1111-4111-8111-111111111111", "verifiedBy": "11111111-1111-4111-8111-111111111111", "verificationNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/software-releases/11111111-1111-4111-8111-111111111111/vehicle-fitments", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FitmentsReplacement" }, "example": { "fitments": [] } } } } } }, "/admin/files": { "get": { "operationId": "adminFiles", "summary": "Manage tuning files", "description": "Staff metadata for all states. version is current published if present, otherwise latest draft. Use /versions for every revision.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Files" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Search public titles/reference labels and any public identifier or AI vehicle/ECU metadata. Identifier lookup is case-insensitive and ignores separators, supporting full values and prefixes; SQL wildcards are escaped." }, { "name": "identifier", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Exact identifier across accepted AI/extractor results, supplements and verified releases. Lookup ignores case and separators; leading and trailing zeroes remain significant. Displayed values retain original punctuation." }, { "name": "identifierKind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "description": "Restrict exact match to an identifier kind." }, { "name": "identifierNamespace", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Manufacturer/system identifier naming scheme." }, { "name": "softwareReleaseId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "ecuManufacturerId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "ecuTypeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "makeId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "modelId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "vehicleVariantId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "ANDed UUID filter. Vehicle results use verified fitments only." }, { "name": "year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1886, "maximum": 2200 }, "description": "Includes variants with a known inclusive year range." }, { "name": "make", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "ecu", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "ecuMaker", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "engine", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "modelYear", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Normalized public identity value. Includes labelled AI candidates; not proof of vehicle compatibility." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] }, "description": "File artifact category." }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": "Uploader-defined public type (stage1, stage2, custom_stage3, unlocked); staff queries retain original version stage." }, { "name": "accessPolicy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "members", "manual_grant", "paid_coming_soon", "staff_only", "credits" ] }, "description": "Listing policy; visible locked listings remain searchable." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "relevance", "updated", "title", "size", "published" ] }, "description": "Default relevance when searching, otherwise updated. Title ascending; size and dates descending; UUID stable secondary sort." }, { "name": "publicationState", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "description": "Include chosen draft/published/archived state." }, { "name": "catalogueVisibility", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "public", "staff_only" ] }, "description": "Visibility filter." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminFilesResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "uploadFile", "summary": "Upload a new draft entry", "description": "Exactly one artifact plus metadata; bounded temporary storage and streamed SHA-256. Creates staff-only draft entry/version in one transaction. Duplicate bytes require explicit acknowledgeDuplicate and a NEW key for the changed payload; independent permissions never merge.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFileResponse" }, "example": { "data": { "fileId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "publicationState": "draft", "reviewState": "draft", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "byteSize": "8388608", "etag": "\"1\"", "file": { "id": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "title": "Example", "description": "Example", "publicationState": "draft", "catalogueVisibility": "public", "accessPolicy": "members", "publishedVersionId": "11111111-1111-4111-8111-111111111111", "plannedPriceMinor": "8388608", "currency": "CAD", "publishedAt": "2026-09-17T12:00:00.000Z", "archivedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "access": { "canDownload": false, "reason": "PURCHASE_NOT_AVAILABLE" }, "createdBy": "11111111-1111-4111-8111-111111111111", "updatedBy": "11111111-1111-4111-8111-111111111111", "publishedBy": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example" }, "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "duplicateContent": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "413": { "description": "Configured body/file size exceeded.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 413, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "UPLOAD_TOO_LARGE", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "metadata": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/UploadMetadata" }, "description": "UTF-8 serialized JSON metadata; maximum64KiB. See UploadMetadata/VersionUploadMetadata schema." }, "file": { "type": "string", "format": "binary", "description": "Exactly one unchanged .bin, .a2l, .pdf, .txt or .md artifact. No archives/executables/HTML." } }, "required": [ "metadata", "file" ], "additionalProperties": false }, "encoding": { "metadata": { "contentType": "application/json" }, "file": { "contentType": "application/octet-stream" } }, "examples": { "original_bin": { "summary": "Synthetic original_bin multipart metadata", "value": { "metadata": "{\"kind\":\"original_bin\",\"title\":\"Synthetic original read\",\"versionLabel\":\"Original read 1\",\"readType\":\"full\",\"readMethod\":\"bench\",\"readTool\":\"Staff-recorded tool\",\"releaseLinks\":[{\"softwareReleaseId\":\"11111111-1111-4111-8111-111111111111\",\"matchStatus\":\"verified\",\"evidenceNote\":\"Synthetic fixture identifiers checked against fixture report.\"}]}", "file": "synthetic-original_bin.bin" } }, "tuned_bin": { "summary": "Synthetic tuned_bin multipart metadata", "value": { "metadata": "{\"kind\":\"tuned_bin\",\"title\":\"Synthetic tuned revision\",\"versionLabel\":\"Revision 1\",\"stage\":\"stage1\",\"baselineOriginalVersionId\":\"22222222-2222-4222-8222-222222222222\",\"fuelRequirement\":\"not specified\",\"hardwareRequirements\":\"not specified\",\"releaseLinks\":[{\"softwareReleaseId\":\"11111111-1111-4111-8111-111111111111\",\"matchStatus\":\"verified\",\"evidenceNote\":\"Synthetic fixture release matches the exact original baseline.\"}]}", "file": "synthetic-tuned_bin.bin" } }, "a2l": { "summary": "Synthetic a2l multipart metadata", "value": { "metadata": "{\"kind\":\"a2l\",\"title\":\"Synthetic definition document\",\"versionLabel\":\"Definition 1\",\"releaseLinks\":[{\"softwareReleaseId\":\"11111111-1111-4111-8111-111111111111\",\"matchStatus\":\"verified\",\"evidenceNote\":\"Synthetic identifiers checked against fixture definition.\"}],\"relations\":[{\"targetVersionId\":\"22222222-2222-4222-8222-222222222222\",\"relationType\":\"definition_for\",\"status\":\"verified\",\"evidenceNote\":\"Synthetic fixture definition shares verified release context.\"}]}", "file": "synthetic-a2l.a2l" } }, "document": { "summary": "Synthetic document multipart metadata", "value": { "metadata": "{\"kind\":\"document\",\"title\":\"Synthetic read report\",\"versionLabel\":\"Report 1\",\"relations\":[{\"targetVersionId\":\"22222222-2222-4222-8222-222222222222\",\"relationType\":\"documentation_for\",\"status\":\"candidate\",\"evidenceNote\":\"Staff review pending for this synthetic fixture.\"}]}", "file": "synthetic-document.pdf" } } } } } } } }, "/admin/files/{fileId}": { "get": { "operationId": "adminFile", "summary": "Read staff file detail", "description": "Includes internal review/access metadata; private staff detail never comes through public route.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Files" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminFileResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "title": "Example", "description": "Example", "publicationState": "draft", "catalogueVisibility": "public", "accessPolicy": "members", "publishedVersionId": "11111111-1111-4111-8111-111111111111", "plannedPriceMinor": "8388608", "currency": "CAD", "publishedAt": "2026-09-17T12:00:00.000Z", "archivedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "access": { "canDownload": false, "reason": "PURCHASE_NOT_AVAILABLE" }, "createdBy": "11111111-1111-4111-8111-111111111111", "updatedBy": "11111111-1111-4111-8111-111111111111", "publishedBy": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateFile", "summary": "Edit file metadata", "description": "Editors prepare drafts/internal notes. Any change to public presentation/policy/visibility/price of an already published record requires admin. Cannot change bytes/kind/publication pointer.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFileResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "title": "Example", "description": "Example", "publicationState": "draft", "catalogueVisibility": "public", "accessPolicy": "members", "publishedVersionId": "11111111-1111-4111-8111-111111111111", "plannedPriceMinor": "8388608", "currency": "CAD", "publishedAt": "2026-09-17T12:00:00.000Z", "archivedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "access": { "canDownload": false, "reason": "PURCHASE_NOT_AVAILABLE" }, "createdBy": "11111111-1111-4111-8111-111111111111", "updatedBy": "11111111-1111-4111-8111-111111111111", "publishedBy": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePatch" }, "example": { "title": "Synthetic original read" } } } } } }, "/admin/files/{fileId}/versions": { "get": { "operationId": "fileVersions", "summary": "List immutable revisions", "description": "All revisions newest first with individual version ETags. Existing published bytes remain current until explicit publication.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Files" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "post": { "operationId": "uploadVersion", "summary": "Upload a new revision", "description": "Requires current FILE ETag. Locks file to allocate unique next versionNo; does not switch published pointer. Cannot change file title/policy through this request. Metadata.kind, if supplied, must match existing kind.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadVersionResponse" }, "example": { "data": { "fileId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "publicationState": "draft", "reviewState": "draft", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "byteSize": "8388608", "etag": "\"1\"", "file": { "id": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "title": "Example", "description": "Example", "publicationState": "draft", "catalogueVisibility": "public", "accessPolicy": "members", "publishedVersionId": "11111111-1111-4111-8111-111111111111", "plannedPriceMinor": "8388608", "currency": "CAD", "publishedAt": "2026-09-17T12:00:00.000Z", "archivedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "access": { "canDownload": false, "reason": "PURCHASE_NOT_AVAILABLE" }, "createdBy": "11111111-1111-4111-8111-111111111111", "updatedBy": "11111111-1111-4111-8111-111111111111", "publishedBy": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example" }, "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "duplicateContent": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "413": { "description": "Configured body/file size exceeded.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 413, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "UPLOAD_TOO_LARGE", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "metadata": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/VersionUploadMetadata" }, "description": "UTF-8 serialized JSON metadata; maximum64KiB. See UploadMetadata/VersionUploadMetadata schema." }, "file": { "type": "string", "format": "binary", "description": "Exactly one unchanged .bin, .a2l, .pdf, .txt or .md artifact. No archives/executables/HTML." } }, "required": [ "metadata", "file" ], "additionalProperties": false }, "encoding": { "metadata": { "contentType": "application/json" }, "file": { "contentType": "application/octet-stream" } }, "examples": { "original_bin": { "summary": "Synthetic original_bin multipart metadata", "value": { "metadata": "{\"kind\":\"original_bin\",\"versionLabel\":\"Original read 1\",\"readType\":\"full\",\"readMethod\":\"bench\",\"readTool\":\"Staff-recorded tool\",\"releaseLinks\":[{\"softwareReleaseId\":\"11111111-1111-4111-8111-111111111111\",\"matchStatus\":\"verified\",\"evidenceNote\":\"Synthetic fixture identifiers checked against fixture report.\"}]}", "file": "synthetic-original_bin.bin" } }, "tuned_bin": { "summary": "Synthetic tuned_bin multipart metadata", "value": { "metadata": "{\"kind\":\"tuned_bin\",\"versionLabel\":\"Revision 1\",\"stage\":\"stage1\",\"baselineOriginalVersionId\":\"22222222-2222-4222-8222-222222222222\",\"fuelRequirement\":\"not specified\",\"hardwareRequirements\":\"not specified\",\"releaseLinks\":[{\"softwareReleaseId\":\"11111111-1111-4111-8111-111111111111\",\"matchStatus\":\"verified\",\"evidenceNote\":\"Synthetic fixture release matches the exact original baseline.\"}]}", "file": "synthetic-tuned_bin.bin" } }, "a2l": { "summary": "Synthetic a2l multipart metadata", "value": { "metadata": "{\"kind\":\"a2l\",\"versionLabel\":\"Definition 1\",\"releaseLinks\":[{\"softwareReleaseId\":\"11111111-1111-4111-8111-111111111111\",\"matchStatus\":\"verified\",\"evidenceNote\":\"Synthetic identifiers checked against fixture definition.\"}],\"relations\":[{\"targetVersionId\":\"22222222-2222-4222-8222-222222222222\",\"relationType\":\"definition_for\",\"status\":\"verified\",\"evidenceNote\":\"Synthetic fixture definition shares verified release context.\"}]}", "file": "synthetic-a2l.a2l" } }, "document": { "summary": "Synthetic document multipart metadata", "value": { "metadata": "{\"kind\":\"document\",\"versionLabel\":\"Report 1\",\"relations\":[{\"targetVersionId\":\"22222222-2222-4222-8222-222222222222\",\"relationType\":\"documentation_for\",\"status\":\"candidate\",\"evidenceNote\":\"Staff review pending for this synthetic fixture.\"}]}", "file": "synthetic-document.pdf" } } } } } } } }, "/admin/files/{fileId}/versions/{versionId}": { "get": { "operationId": "fileVersion", "summary": "Read an exact staff revision", "description": "Both IDs are checked for ownership. Contains staff provenance/release/definition relations without exposing blob identifiers.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Files" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileVersionResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" }, "patch": { "operationId": "updateVersion", "summary": "Edit unlocked version metadata", "description": "Uses VERSION ETag. Bytes/file/version number are immediately immutable; any publication/baseline/association lock prevents identity edits. Existing accepted baseline cannot be replaced; corrections need a new version. Edits reset ready status.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVersionResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionPatch" }, "example": { "versionLabel": "Revision 2" } } } } } }, "/admin/files/{fileId}/versions/{versionId}/releases": { "put": { "operationId": "replaceVersionReleases", "summary": "Replace version release links", "description": "Uses/increments owning VERSION ETag. Verifies bounded IDs/status/evidence. BINs can use saved AI identification or an applicable AI/bundle qualification instead of a manual release association. Conflicting verified releases remain blocked; a revision series cannot silently change software identity.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceVersionReleasesResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/releases", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionReleasesReplacement" }, "example": { "releaseLinks": [] } } } } } }, "/admin/files/{fileId}/versions/{versionId}/relations": { "put": { "operationId": "replaceVersionRelations", "summary": "Replace definition/document links", "description": "Uses owning VERSION ETag. definition_for requires A2L source/BIN target and shared verified release evidence; documentation_for requires document source. Verified targets must be ready and atomically locked. Reject self-links.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceVersionRelationsResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/relations", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRelationsReplacement" }, "example": { "relations": [] } } } } } }, "/admin/files/{fileId}/versions/{versionId}/review": { "post": { "operationId": "reviewVersion", "summary": "Mark ready or rejected", "description": "Uses VERSION ETag. Ready validates stored integrity, exact baseline, verified release and required stage/fuel/hardware state. Review means catalogue completeness, never a claim of ECU test/compatibility.\n\nPermission: editor or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewVersionResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/review", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRequest" }, "example": { "reviewState": "draft" } } } } } }, "/admin/files/{fileId}/versions/{versionId}/download": { "get": { "operationId": "downloadVersion", "summary": "Download exact staff version", "description": "Active verified staff may retrieve exact historic/draft bytes; file/version ownership checked before materialization. Download and audit outcome recorded.\n\nPermission: editor or higher; staff access requires active verified account. ", "tags": [ "Files" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Exact authorized stored bytes; complete 200 response. HEAD returns405 with Allow:GET. No Range/resume support. Completion means the API finished sending, not proof of saving.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "Content-Disposition": { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "Sanitized attachment filename plus UTF-8 filename*." }, "Content-Length": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Exact stored byte count." }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } }, "text/plain": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } }, "text/markdown": { "schema": { "type": "string", "format": "binary", "description": "Unchanged complete attachment bytes; never decode BIN/A2L as JSON or text." } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/download", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/download", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/download", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/download", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "429": { "description": "Shared authentication or transfer admission limit reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Retry-After": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Seconds before retry." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 429, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/download", "code": "RATE_LIMITED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/download", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/versions/11111111-1111-4111-8111-111111111111/download", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "editor" } }, "/admin/files/{fileId}/publish": { "post": { "operationId": "publishFile", "summary": "Publish or roll back to a ready version", "description": "Uses FILE ETag. Atomic pointer change requires own ready version, intact stored bytes, immutable exact baseline/release and deliberately chosen visibility/policy. Older-version rollback uses the same checks; planned price does not grant entitlement.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishFileResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "title": "Example", "description": "Example", "publicationState": "draft", "catalogueVisibility": "public", "accessPolicy": "members", "publishedVersionId": "11111111-1111-4111-8111-111111111111", "plannedPriceMinor": "8388608", "currency": "CAD", "publishedAt": "2026-09-17T12:00:00.000Z", "archivedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "access": { "canDownload": false, "reason": "PURCHASE_NOT_AVAILABLE" }, "createdBy": "11111111-1111-4111-8111-111111111111", "updatedBy": "11111111-1111-4111-8111-111111111111", "publishedBy": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/publish", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRequest" }, "example": { "versionId": "11111111-1111-4111-8111-111111111111", "catalogueVisibility": "public", "accessPolicy": "members" } } } } } }, "/admin/files/{fileId}/archive": { "post": { "operationId": "archiveFile", "summary": "Archive a catalogue entry", "description": "Immediately removes public discovery/customer download regardless of grants; retains bytes/provenance/audit. No hard delete endpoint.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Files" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveFileResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "title": "Example", "description": "Example", "publicationState": "draft", "catalogueVisibility": "public", "accessPolicy": "members", "publishedVersionId": "11111111-1111-4111-8111-111111111111", "plannedPriceMinor": "8388608", "currency": "CAD", "publishedAt": "2026-09-17T12:00:00.000Z", "archivedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "version": { "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionNo": 1, "versionLabel": "Example", "originalFilename": "Example", "mimeType": "Example", "stage": "Example", "publicNotes": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "reviewState": "draft", "validatedAt": "2026-09-17T12:00:00.000Z", "publishedAt": "2026-09-17T12:00:00.000Z", "lockedAt": "2026-09-17T12:00:00.000Z", "lockReason": "publication", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "byteSize": "8388608", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "releases": [], "baselineOriginalVersionId": "11111111-1111-4111-8111-111111111111", "previousVersionId": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example", "validationNotes": "Example", "createdBy": "11111111-1111-4111-8111-111111111111", "validatedBy": "11111111-1111-4111-8111-111111111111" }, "access": { "canDownload": false, "reason": "PURCHASE_NOT_AVAILABLE" }, "createdBy": "11111111-1111-4111-8111-111111111111", "updatedBy": "11111111-1111-4111-8111-111111111111", "publishedBy": "11111111-1111-4111-8111-111111111111", "internalNotes": "Example" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/files/11111111-1111-4111-8111-111111111111/archive", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveRequest" }, "example": { "reason": "Example" } } } } } }, "/admin/users": { "get": { "operationId": "adminUsers", "summary": "List tuning accounts", "description": "Only tuning accounts; no shop/Firebase identity reuse. Hashes/tokens never returned.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Administration" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Bounded email/display-name search." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUsersResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" } }, "/admin/users/{userId}/company-verification": { "get": { "operationId": "adminCompanyVerification", "summary": "Read private company review state", "description": "Active email-verified admin browser session only; current role and session rechecked transactionally. Private notes are restricted to this DTO. Shares the users row ETag.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Administration" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCompanyVerificationResponse" }, "example": { "data": { "companyName": null, "status": "unverified", "companyVerified": false, "userId": "11111111-1111-4111-8111-111111111111", "companyNameSnapshot": null, "verifiedBy": null, "verifiedAt": null, "revokedBy": null, "revokedAt": null, "revocationReason": null, "internalNotes": null, "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" }, "post": { "operationId": "changeCompanyVerification", "summary": "Verify or revoke a company profile", "description": "Dedicated audited browser-session action with a nonblank reason and required If-Match. Self verify, revoke or reverify is allowed only when the authenticated actor ID and target ID identify the same server-loaded user and that current user is an active, email-verified admin whose stored email_normalized is exactly info@redlineautohaus.ca; all other self verification or revocation is forbidden. Request body fields, headers, aliases and client-supplied email or role never grant this exception. Verify binds the current nonempty company of an active account; the server assigns name, actor and time. Private notes remain admin-only. Revoke of unverified/revoked is an authorized no-op after If-Match. Rename/clear/inactive transitions revoke atomically; restoring a name/status never restores verification. Company verification does not certify a file, tune, ECU compatibility, authenticity or safety.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Administration" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeCompanyVerificationResponse" }, "example": { "data": { "companyName": null, "status": "unverified", "companyVerified": false, "userId": "11111111-1111-4111-8111-111111111111", "companyNameSnapshot": null, "verifiedBy": null, "verifiedAt": null, "revokedBy": null, "revokedAt": null, "revocationReason": null, "internalNotes": null, "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/company-verification", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyVerificationAction" }, "example": { "action": "verify", "reason": "Synthetic company review", "internalNotes": null } } } } } }, "/admin/users/{userId}": { "get": { "operationId": "adminUser", "summary": "Read account access", "description": "Sanitized target account and current ETag.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Administration" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "email": "customer@example.test", "displayName": "Example Customer", "companyName": null, "evcLicense": null, "phone": null, "role": "customer", "status": "active", "emailVerifiedAt": "2026-09-17T12:00:00.000Z", "lastLoginAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" }, "patch": { "operationId": "updateUserAccess", "summary": "Change role or status", "description": "Explicit role/status changes revoke affected sessions. Administrators may also set or remove the account's official EVC licence reference without changing company verification or session access. An unverified email cannot be activated. Transactional singleton lock prevents removal of last active verified admin, including concurrent changes.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Administration" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserAccessResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "email": "customer@example.test", "displayName": "Example Customer", "companyName": null, "evcLicense": null, "phone": null, "role": "customer", "status": "active", "emailVerifiedAt": "2026-09-17T12:00:00.000Z", "lastLoginAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserAccessPatch" }, "example": { "role": "editor" } } } } } }, "/admin/users/{userId}/grants": { "get": { "operationId": "userGrants", "summary": "List an account’s grants", "description": "Includes revoked/expired rows with their own ETags for safe revoke/reactivate decisions.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Administration" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserGrantsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" }, "post": { "operationId": "createGrant", "summary": "Create a manual file grant", "description": "One user plus one file entry, optionally future expiry. Covers the current published version, not historic bytes/software-ID siblings. Existing row returns409 GRANT_EXISTS with permitted grant ID in fieldErrors.grantId; explicit PATCH reactivates.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Administration" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "201": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGrantResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "userId": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "grantedBy": "11111111-1111-4111-8111-111111111111", "reason": "Example", "expiresAt": "2026-09-17T12:00:00.000Z", "revokedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/users/11111111-1111-4111-8111-111111111111/grants", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantCreate" }, "example": { "fileId": "11111111-1111-4111-8111-111111111111", "reason": "Example" } } } } } }, "/admin/grants/{grantId}": { "get": { "operationId": "grant", "summary": "Read a grant with ETag", "description": "Returns current manual entitlement row; UI labels/prices do not create authorization.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Administration" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "userId": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "grantedBy": "11111111-1111-4111-8111-111111111111", "reason": "Example", "expiresAt": "2026-09-17T12:00:00.000Z", "revokedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" }, "patch": { "operationId": "updateGrant", "summary": "Update, revoke or reactivate a grant", "description": "reactivate clears revokedAt, records current admin/new reason and supplied future expiry or no expiry. update does not reactivate. Every decision increments rowVersion and writes audit.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Administration" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "name": "grantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Canonical resource UUID; ownership and visibility are checked by the API." }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGrantResponse" }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "userId": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "grantedBy": "11111111-1111-4111-8111-111111111111", "reason": "Example", "expiresAt": "2026-09-17T12:00:00.000Z", "revokedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"" } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "404": { "description": "Resource unknown or not visible.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 404, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "NOT_FOUND", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/grants/11111111-1111-4111-8111-111111111111", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantPatch" }, "example": { "action": "update", "reason": "Example" } } } } } }, "/admin/audit-events": { "get": { "operationId": "auditEvents", "summary": "Read sanitized audit records", "description": "Append-only operational/security metadata, filtered and paginated. No password/token/reset URL/content copies.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Audit" ], "security": [ { "tuningSession": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 1 }, "description": "One-based page; UUID provides stable tie-breaking." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum100 items; metadata only." }, { "name": "actor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Actor user UUID." }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "Exact audit action." }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": "Exact entity type." }, { "name": "entityId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "description": "Entity UUID." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "description": "Inclusive creation start." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "description": "Inclusive creation end." } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventsResponse" }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/audit-events", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/audit-events", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/audit-events", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/audit-events", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/audit-events", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" } }, "/admin/site": { "patch": { "operationId": "updateSite", "summary": "Update approved public settings", "description": "Admin-only audited contact and add-on controls. Four add-on switches require both deployment ceilings and persisted approval. Submissions also require approved rights text/version, active credit policy and completed canonical backfill; acquisition requires a policy. Rights fields must be supplied together, and changed text requires a new version. Active policy/backfill pointers are read-only here. purchaseEnabled/payment settings are not accepted.\n\nPermission: admin or higher; staff access requires active verified account. Approved Origin is required.", "tags": [ "Site" ], "security": [ { "tuningSession": [], "csrfToken": [] } ], "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteResponse" }, "example": { "data": { "id": 1, "branchName": "Example", "parentName": "Example", "parentUrl": "https://redlineautohaus.com/", "publicEmail": "customer@example.test", "phoneDisplay": "Example", "phoneE164": "Example", "addressLine1": "Example", "city": "Example", "region": "Example", "postalCode": "Example", "countryCode": "Ex", "timezone": "Example", "openingHours": { "monday": { "open": "08:00", "close": "18:00" }, "tuesday": { "open": "08:00", "close": "18:00" }, "wednesday": { "open": "08:00", "close": "18:00" }, "thursday": { "open": "08:00", "close": "18:00" }, "friday": { "open": "08:00", "close": "18:00" }, "saturday": { "open": "08:00", "close": "18:00" }, "sunday": { "open": "08:00", "close": "18:00" } }, "identityStatement": "Example", "contactSourceUrl": "https://redlineautohaus.com/", "contactsVerifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "purchaseEnabled": false, "uploadLimits": { "maxBinBytes": 67108864, "maxA2lBytes": 67108864, "maxDocumentBytes": 10485760, "maxMultipartBytes": 68157440, "maxMetadataBytes": 65536 }, "submissionsEnabled": false, "aiResearchEnabled": false, "automaticAcceptanceEnabled": false, "a2lChangedByteCoveragePercent": 90, "creditAcquisitionsEnabled": false, "contributionRightsVersion": "Example", "contributionRightsText": "Example", "activeCreditPolicyId": "11111111-1111-4111-8111-111111111111", "canonicalBackfillCompletedAt": "2026-09-17T12:00:00.000Z", "effectiveAddonSwitches": { "submissionsEnabled": false, "aiResearchEnabled": false, "automaticAcceptanceEnabled": false, "a2lChangedByteCoveragePercent": 90, "creditAcquisitionsEnabled": false } } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "409": { "description": "Immutable, duplicate, idempotency or state conflict.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 409, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "CONFLICT", "requestId": "example-request-20260917" } } } }, "412": { "description": "If-Match no longer matches the current row version.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 412, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "PRECONDITION_FAILED", "requestId": "example-request-20260917" } } } }, "415": { "description": "Unsupported content type or extension.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 415, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "UNSUPPORTED_MEDIA_TYPE", "requestId": "example-request-20260917" } } } }, "422": { "description": "Invalid semantic association or publication precondition.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 422, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "INVALID_ASSOCIATION", "requestId": "example-request-20260917" } } } }, "428": { "description": "Required If-Match missing.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 428, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "IF_MATCH_REQUIRED", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePatch" }, "example": { "phoneDisplay": "+1 519 997 2356" } } } } }, "get": { "operationId": "adminSite", "summary": "Read administrative site and add-on controls", "description": "Returns persisted add-on controls and effective values after deployment kill switches. Public /site omits these administrative fields.\n\nPermission: admin or higher; staff access requires active verified account. ", "tags": [ "Site" ], "security": [ { "tuningSession": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response. Examples are synthetic unless they contain approved public contact settings.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Personal access decisions and downloads are never cached publicly." }, "ETag": { "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Quoted row_version for this resource; use for subsequent If-Match." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSiteResponse" }, "example": { "data": { "id": 1, "branchName": "Example", "parentName": "Example", "parentUrl": "https://redlineautohaus.com/", "publicEmail": "customer@example.test", "phoneDisplay": "Example", "phoneE164": "Example", "addressLine1": "Example", "city": "Example", "region": "Example", "postalCode": "Example", "countryCode": "Ex", "timezone": "Example", "openingHours": { "monday": { "open": "08:00", "close": "18:00" }, "tuesday": { "open": "08:00", "close": "18:00" }, "wednesday": { "open": "08:00", "close": "18:00" }, "thursday": { "open": "08:00", "close": "18:00" }, "friday": { "open": "08:00", "close": "18:00" }, "saturday": { "open": "08:00", "close": "18:00" }, "sunday": { "open": "08:00", "close": "18:00" } }, "identityStatement": "Example", "contactSourceUrl": "https://redlineautohaus.com/", "contactsVerifiedAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "rowVersion": 1, "etag": "\"1\"", "purchaseEnabled": false, "uploadLimits": { "maxBinBytes": 67108864, "maxA2lBytes": 67108864, "maxDocumentBytes": 10485760, "maxMultipartBytes": 68157440, "maxMetadataBytes": 65536 }, "submissionsEnabled": false, "aiResearchEnabled": false, "automaticAcceptanceEnabled": false, "a2lChangedByteCoveragePercent": 90, "creditAcquisitionsEnabled": false, "contributionRightsVersion": "Example", "contributionRightsText": "Example", "activeCreditPolicyId": "11111111-1111-4111-8111-111111111111", "canonicalBackfillCompletedAt": "2026-09-17T12:00:00.000Z", "effectiveAddonSwitches": { "submissionsEnabled": false, "aiResearchEnabled": false, "automaticAcceptanceEnabled": false, "a2lChangedByteCoveragePercent": 90, "creditAcquisitionsEnabled": false } } } } } }, "400": { "description": "Malformed or invalid request.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 400, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "INVALID_FIELD", "requestId": "example-request-20260917" } } } }, "401": { "description": "Session absent or expired.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 401, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "SIGN_IN_REQUIRED", "requestId": "example-request-20260917" } } } }, "403": { "description": "Action, Origin, CSRF or file access not allowed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 403, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "FORBIDDEN", "requestId": "example-request-20260917" } } } }, "500": { "description": "Unexpected error; no internal details are returned.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 500, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "INTERNAL_ERROR", "requestId": "example-request-20260917" } } } }, "503": { "description": "Tuning unavailable or disabled; existing UDS remains isolated.", "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "about:blank", "title": "Request failed", "status": 503, "detail": "The requested operation could not be completed.", "instance": "/api/v1/tuning/admin/site", "code": "TUNING_UNAVAILABLE", "requestId": "example-request-20260917" } } } } }, "x-role": "admin" } }, "/me/api-keys": { "get": { "operationId": "listApiKeys", "summary": "list Api Keys", "tags": [ "Developer access" ], "x-role": "customer", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [], "responses": { "200": { "description": "Operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeveloperKeyList" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "enabled": false, "accountEnabled": false, "baselinePermissions": [], "availablePermissions": [], "keys": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] }, "post": { "operationId": "createApiKey", "summary": "create Api Key", "tags": [ "Developer access" ], "x-role": "customer", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKeyCreate" }, "example": { "name": "Example", "permissions": [], "expiresInDays": 1, "currentPassword": "Example" } } } }, "responses": { "201": { "description": "Created. Save the secret now; it is not retrievable later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeveloperKeyCreated" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "userId": "11111111-1111-4111-8111-111111111111", "name": "Example", "prefix": "Example", "permissions": [], "disabled": false, "adminDisabled": false, "createdAt": "2026-09-17T12:00:00.000Z", "expiresAt": "2026-09-17T12:00:00.000Z", "revokedAt": "2026-09-17T12:00:00.000Z", "lastUsedAt": "2026-09-17T12:00:00.000Z", "etag": "Example", "status": "active", "secret": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/me/api-keys/revoke-all": { "post": { "operationId": "revokeAllApiKeys", "summary": "revoke All Api Keys", "tags": [ "Developer access" ], "x-role": "customer", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperConfirmation" }, "example": { "currentPassword": "Example" } } } }, "responses": { "204": { "description": "Operation completed.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/me/api-keys/{id}": { "patch": { "operationId": "updateApiKey", "summary": "update Api Key", "tags": [ "Developer access" ], "x-role": "customer", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKeyPatch" }, "example": { "currentPassword": "Example" } } } }, "responses": { "200": { "description": "Operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeveloperKey" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "userId": "11111111-1111-4111-8111-111111111111", "name": "Example", "prefix": "Example", "permissions": [], "disabled": false, "adminDisabled": false, "createdAt": "2026-09-17T12:00:00.000Z", "expiresAt": "2026-09-17T12:00:00.000Z", "revokedAt": "2026-09-17T12:00:00.000Z", "lastUsedAt": "2026-09-17T12:00:00.000Z", "etag": "Example", "status": "active" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] }, "delete": { "operationId": "revokeApiKey", "summary": "revoke Api Key", "tags": [ "Developer access" ], "x-role": "customer", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperConfirmation" }, "example": { "currentPassword": "Example" } } } }, "responses": { "204": { "description": "Operation completed.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/me/api-keys/{id}/rotate": { "post": { "operationId": "rotateApiKey", "summary": "rotate Api Key", "tags": [ "Developer access" ], "x-role": "customer", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperKeyRotate" }, "example": { "expiresInDays": 1, "overlapMinutes": 0, "currentPassword": "Example" } } } }, "responses": { "201": { "description": "Created. Save the secret now; it is not retrievable later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DeveloperKeyCreated" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "userId": "11111111-1111-4111-8111-111111111111", "name": "Example", "prefix": "Example", "permissions": [], "disabled": false, "adminDisabled": false, "createdAt": "2026-09-17T12:00:00.000Z", "expiresAt": "2026-09-17T12:00:00.000Z", "revokedAt": "2026-09-17T12:00:00.000Z", "lastUsedAt": "2026-09-17T12:00:00.000Z", "etag": "Example", "status": "active", "secret": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/api-access/users": { "get": { "operationId": "findApiAccounts", "summary": "find Api Accounts", "tags": [ "Developer access" ], "x-role": "admin", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Name or email prefix. Up to 25 accounts." } ], "responses": { "200": { "description": "Operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperAccount" } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/admin/api-access/users/{id}": { "patch": { "operationId": "updateApiAccount", "summary": "update Api Account", "tags": [ "Developer access" ], "x-role": "admin", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAccountPatch" }, "example": { "apiAccessEnabled": false, "requestsPerMinute": 1, "currentPassword": "Example", "reason": "Example" } } } }, "responses": { "204": { "description": "Operation completed.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/api-access/keys": { "get": { "operationId": "adminListApiKeys", "summary": "admin List Api Keys", "tags": [ "Developer access" ], "x-role": "admin", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperKey" } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/admin/api-access/keys/{id}": { "patch": { "operationId": "adminUpdateApiKey", "summary": "admin Update Api Key", "tags": [ "Developer access" ], "x-role": "admin", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeveloperAdminKeyPatch" }, "example": { "permissions": [], "disabled": false, "currentPassword": "Example", "reason": "Example" } } } }, "responses": { "204": { "description": "Operation completed.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/api-access/uds": { "get": { "operationId": "getUdsApiAdministration", "summary": "get Uds Api Administration", "tags": [ "Developer access" ], "x-role": "admin", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [], "responses": { "200": { "description": "Operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UdsApiAdministration" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "policy": { "approve": false, "revise": false, "redact": false, "publish": false, "etag": "Example" }, "scopes": [], "grants": [], "credentials": [], "events": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] }, "patch": { "operationId": "updateUdsApiPolicy", "summary": "update Uds Api Policy", "tags": [ "Developer access" ], "x-role": "admin", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants.", "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UdsApiPolicyPatch" }, "example": { "approve": false, "revise": false, "redact": false, "publish": false, "currentPassword": "Example", "reason": "Example" } } } }, "responses": { "204": { "description": "Operation completed.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/api-access/uds/grants": { "put": { "operationId": "setUdsAdministrativeGrant", "summary": "set Uds Administrative Grant", "tags": [ "Developer access" ], "x-role": "admin", "description": "Browser session only; developer keys cannot manage keys or grant themselves permissions. Mutations require current-password reauthentication and CSRF. Every active key includes UDS evidence submission. Administrative capabilities also require policy and scope grants. Send If-Match: \"1\" when creating a new grant; when editing use its returned etag.", "parameters": [ { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UdsAdministrativeGrant" }, "example": { "principalType": "developer", "principalId": "Example", "scopeId": "11111111-1111-4111-8111-111111111111", "capabilities": [], "disabled": false, "currentPassword": "Example", "reason": "Example" } } } }, "responses": { "204": { "description": "Operation completed.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/me/credits": { "get": { "operationId": "getCreditWallet", "summary": "Read spendable balance and separate pending reward estimate", "x-permission": "verified_customer", "parameters": [], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditWallet" } }, "required": [ "data" ] }, "example": { "data": { "balance": "30", "accountRestriction": "none", "pendingRewardEstimate": "0" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Read spendable balance and separate pending reward estimate. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Credits" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/me/credits/ledger": { "get": { "operationId": "getCreditLedger", "summary": "Read own append-only credit history", "x-permission": "verified_customer", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLedgerEntry" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 0, "pageSize": 0, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Read own append-only credit history. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Credits" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/me/acquisitions": { "get": { "operationId": "getAcquiredVersions", "summary": "Read exact-version access and current availability", "x-permission": "verified_customer", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AcquiredVersion" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 0, "pageSize": 0, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Read exact-version access and current availability. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Credits" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/files/{fileId}/download-quote": { "post": { "operationId": "quoteDownload", "summary": "Snapshot one version price without reserving or spending credits", "x-permission": "verified_customer", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadQuoteRequest" }, "example": { "versionId": "11111111-1111-4111-8111-111111111111" } } } }, "responses": { "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DownloadQuote" } }, "required": [ "data" ] }, "example": { "data": { "quoteId": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "price": "0", "expiresAt": "2026-09-17T12:00:00.000Z", "alreadyEntitled": false, "balance": "30", "policyId": "11111111-1111-4111-8111-111111111111" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Snapshot one version price without reserving or spending credits. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/download-acquisitions": { "post": { "operationId": "acquireDownload", "summary": "Atomically acquire one quoted exact version; retries never charge twice", "x-permission": "verified_customer", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadAcquisitionRequest" }, "example": { "quoteId": "11111111-1111-4111-8111-111111111111" } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DownloadAcquisition" } }, "required": [ "data" ] }, "example": { "data": { "acquisitionId": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "charge": "0", "balance": "30", "alreadyEntitled": false, "downloadUrl": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/DownloadAcquisition" } }, "required": [ "data" ] }, "example": { "data": { "acquisitionId": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "charge": "0", "balance": "30", "alreadyEntitled": false, "downloadUrl": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Atomically acquire one quoted exact version; retries never charge twice. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:spend. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Credits" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:spend" } }, "/admin/credit-policies": { "get": { "operationId": "getCreditPolicies", "summary": "Read immutable policy versions and activation history", "x-permission": "admin", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditPolicyRecord" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 0, "pageSize": 0, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Read immutable policy versions and activation history. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [] } ] }, "post": { "operationId": "createCreditPolicy", "summary": "Create a policy without activating it; prices must exceed positive rewards", "x-permission": "admin", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCreditPolicy" }, "example": { "stockReward": "10", "stockPrice": "30", "a2lReward": "50", "a2lPrice": "150", "tunedReward": "20", "tunedPrice": "60", "effectiveAt": "2026-09-17T00:00:00.000Z", "reason": "Synthetic example policy; production rates require approval." } } } }, "responses": { "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditPolicyRecord" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "version": 1, "stockReward": "30", "stockPrice": "30", "a2lReward": "30", "a2lPrice": "30", "tunedReward": "30", "tunedPrice": "30", "reason": "Example", "effectiveAt": "2026-09-17T12:00:00.000Z", "activatedAt": "2026-09-17T12:00:00.000Z", "isActive": false, "etag": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Create a policy without activating it; prices must exceed positive rewards. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/credit-policies/{id}/activate": { "post": { "operationId": "activateCreditPolicy", "summary": "Activate policy after validating every current file override", "x-permission": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditReason" }, "example": { "reason": "Example" } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditPolicyRecord" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "version": 1, "stockReward": "30", "stockPrice": "30", "a2lReward": "30", "a2lPrice": "30", "tunedReward": "30", "tunedPrice": "30", "reason": "Example", "effectiveAt": "2026-09-17T12:00:00.000Z", "activatedAt": "2026-09-17T12:00:00.000Z", "isActive": false, "etag": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Activate policy after validating every current file override. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/credit-adjustments": { "post": { "operationId": "adjustCredits", "summary": "Append documented signed adjustment; never patch history", "x-permission": "admin", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditAdjustmentRequest" }, "example": { "userId": "11111111-1111-4111-8111-111111111111", "amount": "30", "reason": "Example" } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditMutation" } }, "required": [ "data" ] }, "example": { "data": { "ledgerEntryId": "11111111-1111-4111-8111-111111111111", "amount": "30", "balance": "30", "accountRestriction": "none" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditMutation" } }, "required": [ "data" ] }, "example": { "data": { "ledgerEntryId": "11111111-1111-4111-8111-111111111111", "amount": "30", "balance": "30", "accountRestriction": "none" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Append documented signed adjustment; never patch history. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/reward-claims/{id}/reverse": { "post": { "operationId": "reverseReward", "summary": "Compensate a reward once and retain its consumed canonical claim", "x-permission": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditReason" }, "example": { "reason": "Example" } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditMutation" } }, "required": [ "data" ] }, "example": { "data": { "ledgerEntryId": "11111111-1111-4111-8111-111111111111", "amount": "30", "balance": "30", "accountRestriction": "none" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditMutation" } }, "required": [ "data" ] }, "example": { "data": { "ledgerEntryId": "11111111-1111-4111-8111-111111111111", "amount": "30", "balance": "30", "accountRestriction": "none" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Compensate a reward once and retain its consumed canonical claim. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/download-acquisitions/{id}/refund": { "post": { "operationId": "refundAcquisition", "summary": "Refund once and revoke the affected entitlement", "x-permission": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditReason" }, "example": { "reason": "Example" } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditMutation" } }, "required": [ "data" ] }, "example": { "data": { "ledgerEntryId": "11111111-1111-4111-8111-111111111111", "amount": "30", "balance": "30", "accountRestriction": "none" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditMutation" } }, "required": [ "data" ] }, "example": { "data": { "ledgerEntryId": "11111111-1111-4111-8111-111111111111", "amount": "30", "balance": "30", "accountRestriction": "none" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Refund once and revoke the affected entitlement. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/credits/{userId}/restriction": { "patch": { "operationId": "restrictCreditWallet", "summary": "Set an audited review hold without deleting credits", "x-permission": "admin", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRestrictionRequest" }, "example": { "restriction": "none", "reason": "Example" } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/WalletRestriction" } }, "required": [ "data" ] }, "example": { "data": { "balance": "30", "accountRestriction": "none", "etag": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Set an audited review hold without deleting credits. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/contribution-items/{itemId}/decision": { "post": { "operationId": "decideContributionItem", "summary": "Apply mandatory gates and atomically publish and reward unique accepted content", "x-permission": "admin", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContributionDecisionRequest" }, "example": { "decision": "accept", "reason": "Example", "evidenceIds": [] } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionDecision" } }, "required": [ "data" ] }, "example": { "data": { "itemId": "11111111-1111-4111-8111-111111111111", "state": "accepted", "reasonCode": "Example", "rewardState": "pending", "rewardAmount": "30", "canonicalContributionId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "etag": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Apply mandatory gates and atomically publish and reward unique accepted content. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/contribution-items/{itemId}/evidence": { "post": { "operationId": "recordStockProvenance", "summary": "Record genuine staff provenance for the current stock verification attempt", "x-permission": "admin", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffProvenanceRequest" }, "example": { "summary": "Example", "sourceReference": "Example", "basis": "documented_original_read" } } } }, "responses": { "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StaffProvenance" } }, "required": [ "data" ] }, "example": { "data": { "evidenceId": "11111111-1111-4111-8111-111111111111", "verificationRunId": "11111111-1111-4111-8111-111111111111", "basis": "documented_original_read" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Record genuine staff provenance for the current stock verification attempt. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/contribution-items/{itemId}/duplicate-candidates": { "get": { "operationId": "getDuplicateCandidates", "summary": "Find bounded staff-only exact hash or shared software review candidates", "x-permission": "editor", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateCandidate" } } }, "required": [ "data" ] }, "example": { "data": [] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "editor", "description": "Find bounded staff-only exact hash or shared software review candidates. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] } ] } }, "/admin/contribution-items/{itemId}/equivalence": { "post": { "operationId": "recordStaffEquivalence", "summary": "Record proof-backed equivalence without merging rewarded identities", "x-permission": "admin", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffEquivalenceRequest" }, "example": { "canonicalContributionId": "11111111-1111-4111-8111-111111111111", "reason": "Example", "sourceReference": "Example", "evidenceIds": [] } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionDecision" } }, "required": [ "data" ] }, "example": { "data": { "itemId": "11111111-1111-4111-8111-111111111111", "state": "accepted", "reasonCode": "Example", "rewardState": "pending", "rewardAmount": "30", "canonicalContributionId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "etag": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Record proof-backed equivalence without merging rewarded identities. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/file-versions/{versionId}/stock-associations": { "post": { "operationId": "appendA2lStockAssociation", "summary": "Append an exact evidenced stock association without another reward", "x-permission": "admin", "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StockAssociationRequest" }, "example": { "stockVersionId": "11111111-1111-4111-8111-111111111111", "reason": "Example", "evidenceIds": [] } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StockAssociation" } }, "required": [ "data" ] }, "example": { "data": { "relationId": "11111111-1111-4111-8111-111111111111", "sourceVersionId": "11111111-1111-4111-8111-111111111111", "stockVersionId": "11111111-1111-4111-8111-111111111111", "alreadyAssociated": false, "reward": "0" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "201": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StockAssociation" } }, "required": [ "data" ] }, "example": { "data": { "relationId": "11111111-1111-4111-8111-111111111111", "sourceVersionId": "11111111-1111-4111-8111-111111111111", "stockVersionId": "11111111-1111-4111-8111-111111111111", "alreadyAssociated": false, "reward": "0" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Append an exact evidenced stock association without another reward. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/file-versions/{versionId}/credit-review": { "post": { "operationId": "reviewLegacyCredits", "summary": "Review legacy bytes using an exact inspected attempt without retroactive rewards", "x-permission": "admin", "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyCreditReviewRequest" }, "example": { "verificationItemId": "11111111-1111-4111-8111-111111111111", "reason": "Example", "evidenceIds": [] } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LegacyCreditReview" } }, "required": [ "data" ] }, "example": { "data": { "versionId": "11111111-1111-4111-8111-111111111111", "canonicalContributionId": "11111111-1111-4111-8111-111111111111", "reviewState": "accepted", "creditEnrolled": false, "retroactiveReward": "0", "etag": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Review legacy bytes using an exact inspected attempt without retroactive rewards. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/file-versions/{versionId}/withdraw": { "post": { "operationId": "withdrawFileVersion", "summary": "Block this version and place dependent versions on review hold", "x-permission": "admin", "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditReason" }, "example": { "reason": "Example" } } } }, "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/VersionWithdrawal" } }, "required": [ "data" ] }, "example": { "data": { "versionId": "11111111-1111-4111-8111-111111111111", "withdrawalState": "withdrawn", "affectedVersionIds": [], "entitlementReview": [], "rewardReview": [], "automaticCompensation": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Block this version and place dependent versions on review hold. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/credits": { "get": { "operationId": "getAdminCreditWallet", "summary": "Inspect a user balance and restriction with its ETag", "x-permission": "admin", "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreditWallet" } }, "required": [ "data" ] }, "example": { "data": { "balance": "30", "accountRestriction": "none", "pendingRewardEstimate": "0" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Inspect a user balance and restriction with its ETag. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [] } ] } }, "/admin/credit-ledger": { "get": { "operationId": "getAdminCreditLedger", "summary": "Audit a user credit history", "x-permission": "admin", "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CreditLedgerEntry" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 0, "pageSize": 0, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Audit a user credit history. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [] } ] } }, "/admin/reward-claims": { "get": { "operationId": "getAdminRewardClaims", "summary": "Inspect reward claim and reversal identifiers", "x-permission": "admin", "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminRewardClaim" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 0, "pageSize": 0, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Inspect reward claim and reversal identifiers. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] } ] } }, "/admin/download-acquisitions": { "get": { "operationId": "getAdminAcquisitions", "summary": "Inspect acquisition and refund identifiers", "x-permission": "admin", "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recorded outcome; decimal credit amounts are strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminDownloadAcquisition" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 0, "pageSize": 0, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Visibility, state, hard verification gate or credit restriction failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Inspect acquisition and refund identifiers. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Credits" ], "security": [ { "tuningSession": [] } ] } }, "/files/{fileId}/versions/{versionId}/download": { "get": { "operationId": "downloadExactVersion", "summary": "Download unchanged acquired bytes without a credit debit", "x-permission": "verified_customer", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Exact-version attachment with no-store caching; never silently substitutes a newer version.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." }, "Content-Disposition": { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "Sanitized attachment filename plus UTF-8 filename*." }, "Content-Length": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Exact stored byte count." }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Redline-DME-Role": { "description": "Optional allowlisted DME side for this exact authorized version; no sibling or set identity.", "schema": { "type": "string", "enum": [ "single", "master", "slave" ] } }, "X-Redline-File-Role": { "description": "Optional allowlisted role for this exact authorized version.", "schema": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } } } }, "default": { "description": "Account, entitlement, publication or withdrawal restriction", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Download unchanged acquired bytes without a credit debit. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:download. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:download" } }, "/contribution-config": { "get": { "operationId": "getContributionConfig", "summary": "Inspect effective submission limits, terms and reward estimates", "x-permission": "public", "parameters": [], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionConfig" } }, "required": [ "data" ] }, "example": { "data": { "enabled": false, "kinds": [], "limits": { "maxBinBytes": 1, "maxA2lBytes": 1, "maxMultipartBytes": 1, "maxMetadataBytes": 1, "maxItemsPerContribution": 1 }, "dependencyRules": { "original_bin": [], "a2l": [ "stock_baseline" ], "tuned_bin": [ "stock_baseline", "matching_a2l" ] }, "dependencyRulesByModificationType": { "unlocked": [ "stock_baseline" ] }, "estimatedRewards": { "original_bin": "0", "a2l": "0", "tuned_bin": "0" }, "proposedRewards": { "original_bin": "0", "a2l": "0", "tuned_bin": "0" }, "limitations": [], "rightsTerms": { "version": "Example", "text": "Example" }, "multiDme": { "enabled": false, "submissionReady": false, "maxSets": 2, "maxRolesPerSet": 4, "dmeRoles": [ "single", "master", "slave" ], "fileRoles": [ "original", "a2l", "stage1", "stage2" ], "workerContextVersion": "2" } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "public", "description": "Inspect effective submission limits, terms and reward estimates. Public capability metadata; no private uploads or evidence. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/contributions": { "post": { "operationId": "createContribution", "summary": "Create an owned unpublished contribution draft", "x-permission": "verified_customer", "parameters": [ { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContribution" }, "example": {} } } }, "responses": { "201": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/CreatedContribution" } }, "required": [ "data" ] }, "example": { "data": { "contributionId": "11111111-1111-4111-8111-111111111111", "state": "draft", "etag": "\"1\"" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Create an owned unpublished contribution draft. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" }, "get": { "operationId": "listOwnContributions", "summary": "Resume owned contribution history and actual per-item outcomes", "x-permission": "verified_customer", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContributionDetail" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalItems": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 1, "pageSize": 1, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Resume owned contribution history and actual per-item outcomes. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/contributions/{id}": { "get": { "operationId": "getOwnContribution", "summary": "Read the owned persisted contribution snapshot", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionDetail" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "state": "draft", "submittedAt": "2026-09-17T12:00:00.000Z", "completedAt": "2026-09-17T12:00:00.000Z", "cancelledAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "etag": "\"1\"", "eventSequence": "0", "items": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Read the owned persisted contribution snapshot. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/contributions/{id}/items/{itemId}/replace": { "post": { "operationId": "replaceContributionItem", "summary": "Upload a replacement and recheck related files while retaining the original review history", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "properties": { "file": { "type": "string", "format": "binary" }, "metadata": { "type": "string", "maxLength": 65536, "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/ReplaceItemMetadata" } } }, "required": [ "file", "metadata" ] } } } }, "responses": { "202": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionDetail" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "state": "draft", "submittedAt": "2026-09-17T12:00:00.000Z", "completedAt": "2026-09-17T12:00:00.000Z", "cancelledAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "etag": "\"1\"", "eventSequence": "0", "items": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Upload a replacement and recheck related files while retaining the original review history. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/contributions/{id}/items": { "post": { "operationId": "uploadContributionItem", "summary": "Stage one exact immutable file with unverified customer claims", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/Idempotency" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "additionalProperties": false, "properties": { "file": { "type": "string", "format": "binary" }, "metadata": { "type": "string", "maxLength": 65536, "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/UploadItemMetadata" } } }, "required": [ "file", "metadata" ] } } } }, "responses": { "201": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/UploadedItem" } }, "required": [ "data" ] }, "example": { "data": { "itemId": "11111111-1111-4111-8111-111111111111", "versionId": "11111111-1111-4111-8111-111111111111", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "byteSize": "1", "etag": "\"1\"" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Stage one exact immutable file with unverified customer claims. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" } }, "/contributions/{id}/items/{itemId}": { "patch": { "operationId": "editDraftContributionClaims", "summary": "Correct claims before submission without replacing bytes", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditItem" }, "example": { "claims": { "vehicle": { "make": "Example", "model": "Example", "year": 1900, "variant": "Example", "engine": "Example", "market": "Example" }, "ecu": "Example", "description": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "provenance": "Example", "permissionConfirmed": false, "permissionTextVersion": "Example", "identifiers": [], "stage": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "testingEvidence": "Example" } } } } }, "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionItem" } }, "required": [ "data" ] }, "example": { "data": { "identityEnrichment": { "state": "queued", "message": "Example", "updatedAt": "2026-09-17T12:00:00.000Z", "identifiedFields": [], "unresolvedFields": [] }, "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "clientItemId": "1", "versionId": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "originalFilename": "Example", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "byteSize": "1", "claims": { "vehicle": { "make": "Example", "model": "Example", "year": 1900, "variant": "Example", "engine": "Example", "market": "Example" }, "ecu": "Example", "description": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "provenance": "Example", "permissionConfirmed": false, "permissionTextVersion": "Example", "identifiers": [], "stage": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "testingEvidence": "Example" }, "state": "draft", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "decisionSummary": "Example", "publicationState": "draft", "retryable": false, "rewardState": "pending", "rewardAmount": "0", "etag": "\"1\"", "versionEtag": "\"1\"", "latestVerificationRunId": "11111111-1111-4111-8111-111111111111", "dependencies": [], "job": { "id": "11111111-1111-4111-8111-111111111111", "state": "queued", "stage": "queued", "eventSequence": "0", "attemptCount": 0, "lastErrorCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "etag": "\"1\"" }, "findings": { "format": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "ecuIdentity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "softwareIdentity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "vehicleFitment": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "stockOriginality": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "dependencyMatch": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "integrity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "uniqueness": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] } }, "evidence": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Correct claims before submission without replacing bytes. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" }, "delete": { "operationId": "deleteDraftContributionItem", "summary": "Delete an unreferenced draft item while retaining immutable blob cleanup policy", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContribution" }, "example": {} } } }, "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionDetail" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "state": "draft", "submittedAt": "2026-09-17T12:00:00.000Z", "completedAt": "2026-09-17T12:00:00.000Z", "cancelledAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "etag": "\"1\"", "eventSequence": "0", "items": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Delete an unreferenced draft item while retaining immutable blob cleanup policy. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" } }, "/contributions/{id}/items/{itemId}/metadata": { "patch": { "operationId": "editOwnContributionMetadata", "summary": "Edit the uploader description and stage in any contribution state using metadataEtag; immutable verification inputs and approval are unchanged", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditItemMetadata" }, "example": { "description": "Example", "tuningStage": "stage1" } } } }, "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionItem" } }, "required": [ "data" ] }, "example": { "data": { "identityEnrichment": { "state": "queued", "message": "Example", "updatedAt": "2026-09-17T12:00:00.000Z", "identifiedFields": [], "unresolvedFields": [] }, "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "clientItemId": "1", "versionId": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "originalFilename": "Example", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "byteSize": "1", "claims": { "vehicle": { "make": "Example", "model": "Example", "year": 1900, "variant": "Example", "engine": "Example", "market": "Example" }, "ecu": "Example", "description": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "provenance": "Example", "permissionConfirmed": false, "permissionTextVersion": "Example", "identifiers": [], "stage": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "testingEvidence": "Example" }, "state": "draft", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "decisionSummary": "Example", "publicationState": "draft", "retryable": false, "rewardState": "pending", "rewardAmount": "0", "etag": "\"1\"", "versionEtag": "\"1\"", "latestVerificationRunId": "11111111-1111-4111-8111-111111111111", "dependencies": [], "job": { "id": "11111111-1111-4111-8111-111111111111", "state": "queued", "stage": "queued", "eventSequence": "0", "attemptCount": 0, "lastErrorCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "etag": "\"1\"" }, "findings": { "format": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "ecuIdentity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "softwareIdentity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "vehicleFitment": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "stockOriginality": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "dependencyMatch": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "integrity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "uniqueness": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] } }, "evidence": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Edit the uploader description and stage in any contribution state using metadataEtag; immutable verification inputs and approval are unchanged. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" } }, "/contributions/{id}/items/{itemId}/dependencies": { "put": { "operationId": "setDraftContributionDependencies", "summary": "Select owned or visible accepted exact-version dependencies", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDependencies" }, "example": {} } } }, "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionItem" } }, "required": [ "data" ] }, "example": { "data": { "identityEnrichment": { "state": "queued", "message": "Example", "updatedAt": "2026-09-17T12:00:00.000Z", "identifiedFields": [], "unresolvedFields": [] }, "id": "11111111-1111-4111-8111-111111111111", "fileId": "11111111-1111-4111-8111-111111111111", "clientItemId": "1", "versionId": "11111111-1111-4111-8111-111111111111", "kind": "original_bin", "originalFilename": "Example", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "byteSize": "1", "claims": { "vehicle": { "make": "Example", "model": "Example", "year": 1900, "variant": "Example", "engine": "Example", "market": "Example" }, "ecu": "Example", "description": "Example", "readType": "full", "readMethod": "obd", "readTool": "Example", "provenance": "Example", "permissionConfirmed": false, "permissionTextVersion": "Example", "identifiers": [], "stage": "Example", "fuelRequirement": "Example", "hardwareRequirements": "Example", "testingEvidence": "Example" }, "state": "draft", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "decisionSummary": "Example", "publicationState": "draft", "retryable": false, "rewardState": "pending", "rewardAmount": "0", "etag": "\"1\"", "versionEtag": "\"1\"", "latestVerificationRunId": "11111111-1111-4111-8111-111111111111", "dependencies": [], "job": { "id": "11111111-1111-4111-8111-111111111111", "state": "queued", "stage": "queued", "eventSequence": "0", "attemptCount": 0, "lastErrorCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "etag": "\"1\"" }, "findings": { "format": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "ecuIdentity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "softwareIdentity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "vehicleFitment": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "stockOriginality": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "dependencyMatch": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "integrity": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] }, "uniqueness": { "status": "pass", "reasonCode": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "summary": "Example", "evidenceKeys": [] } }, "evidence": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Select owned or visible accepted exact-version dependencies. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" } }, "/contribution-dependencies": { "get": { "operationId": "searchContributionDependencies", "summary": "Search eligible exact stock/A2L metadata without granting downloads", "x-permission": "verified_customer", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "kind", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "original_bin", "a2l" ] } }, { "name": "contributionId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "stockVersionId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "ecuTypeId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "softwareReleaseId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DependencyOption" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalItems": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 1, "pageSize": 1, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Search eligible exact stock/A2L metadata without granting downloads. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/contributions/{id}/submit": { "post": { "operationId": "submitContribution", "summary": "Freeze claims, terms and rewards and durably enqueue verification", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitContribution" }, "example": {} } } }, "responses": { "202": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/SubmittedContribution" } }, "required": [ "data" ] }, "example": { "data": { "contributionId": "11111111-1111-4111-8111-111111111111", "itemStates": [], "jobIds": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Freeze claims, terms and rewards and durably enqueue verification. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" } }, "/contributions/{id}/items/{itemId}/retry": { "post": { "operationId": "retryContributionVerification", "summary": "Retry a bounded infrastructure failure against identical immutable inputs", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryItem" }, "example": {} } } }, "responses": { "202": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RetriedItem" } }, "required": [ "data" ] }, "example": { "data": { "contributionId": "11111111-1111-4111-8111-111111111111", "itemId": "11111111-1111-4111-8111-111111111111", "jobId": "11111111-1111-4111-8111-111111111111", "state": "queued" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Retry a bounded infrastructure failure against identical immutable inputs. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" } }, "/contributions/{id}/cancel": { "post": { "operationId": "cancelContribution", "summary": "Cancel pending work transactionally and retain completed decisions", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": false, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Required for browser-session authentication; not for a Redline Bearer key." }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelContribution" }, "example": {} } } }, "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionDetail" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "state": "draft", "submittedAt": "2026-09-17T12:00:00.000Z", "completedAt": "2026-09-17T12:00:00.000Z", "cancelledAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "etag": "\"1\"", "eventSequence": "0", "items": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "description": "Cancel pending work transactionally and retain completed decisions. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present. Alternatively use a Redline API key with tuning:upload. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:upload" } }, "/admin/contribution-reviews": { "get": { "operationId": "listContributionReviews", "summary": "Inspect staff review queue with safe parser evidence and reward status", "x-permission": "editor", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "dependencyHold", "in": "query", "schema": { "type": "boolean" } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "draft", "queued", "processing", "waiting_dependencies", "needs_review", "accepted", "duplicate", "rejected", "failed", "withdrawn" ] } }, { "name": "itemKind", "in": "query", "schema": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContributionReview" } }, "page": { "type": "object", "additionalProperties": false, "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalItems": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ] } }, "required": [ "data", "page" ] }, "example": { "data": [], "page": { "page": 1, "pageSize": 1, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "editor", "description": "Inspect staff review queue with safe parser evidence and reward status. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] } ] } }, "/admin/contributions/{id}": { "get": { "operationId": "getAdminContribution", "summary": "Inspect contribution evidence and exact dependency graph", "x-permission": "editor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ContributionReview" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "state": "draft", "submittedAt": "2026-09-17T12:00:00.000Z", "completedAt": "2026-09-17T12:00:00.000Z", "cancelledAt": "2026-09-17T12:00:00.000Z", "createdAt": "2026-09-17T12:00:00.000Z", "updatedAt": "2026-09-17T12:00:00.000Z", "etag": "\"1\"", "eventSequence": "0", "items": [], "user": { "id": "11111111-1111-4111-8111-111111111111", "email": "customer@example.test", "displayName": "Example" } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "editor", "description": "Inspect contribution evidence and exact dependency graph. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] } ] } }, "/admin/contribution-items/{itemId}/review-context": { "get": { "operationId": "getStaffReviewContext", "summary": "Inspect approval blockers, saved AI identity and decision history without changing the file", "x-permission": "editor", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/StaffReviewContext" } }, "required": [ "data" ] }, "example": { "data": { "itemId": "11111111-1111-4111-8111-111111111111", "etag": "Example", "canApprove": false, "blockers": [], "identity": { "software": [], "ecuVariants": [], "records": [] }, "dependencies": [], "history": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "editor", "description": "Inspect approval blockers, saved AI identity and decision history without changing the file. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] } ] } }, "/admin/contribution-items/{itemId}/reverify": { "post": { "operationId": "reverifyContributionItem", "summary": "Append verification of immutable inputs without awarding again; restartInterrupted restricts the action to failed or expired checks", "x-permission": "admin", "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverifyItem" }, "example": { "reason": "Example" } } } }, "responses": { "202": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/RetriedItem" } }, "required": [ "data" ] }, "example": { "data": { "contributionId": "11111111-1111-4111-8111-111111111111", "itemId": "11111111-1111-4111-8111-111111111111", "jobId": "11111111-1111-4111-8111-111111111111", "state": "queued" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Append verification of immutable inputs without awarding again; restartInterrupted restricts the action to failed or expired checks. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/admin/verification-profiles": { "get": { "operationId": "listVerificationProfiles", "summary": "List already deployed immutable verification profiles", "x-permission": "admin", "parameters": [], "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationProfile" } } }, "required": [ "data" ] }, "example": { "data": [] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "List already deployed immutable verification profiles. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] } ] } }, "/admin/verification-profiles/{id}": { "patch": { "operationId": "activateVerificationProfile", "summary": "Audit activation of deployed and qualified capabilities", "x-permission": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileActivation" }, "example": { "enabled": false, "autoAcceptEnabled": false } } } }, "responses": { "200": { "description": "Persisted scoped result; byte sizes, sequence IDs and credit amounts are decimal strings.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/VerificationProfile" } }, "required": [ "data" ] }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "profileKey": "Example", "profileVersion": "Example", "adapterKey": "Example", "kind": "original_bin", "dumpLayout": "Example", "capabilities": [], "enabled": false, "autoAcceptEnabled": false, "etag": "Example" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "admin", "description": "Audit activation of deployed and qualified capabilities. Active verified tuning account required; ownership and current state are rechecked. Decimal credit amounts are strings. Mutation retries must preserve the original Idempotency-Key and If-Match value when present.", "tags": [ "Contributions" ], "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/contributions/{id}/events": { "get": { "operationId": "streamContributionProgress", "summary": "Replay owned persisted progress by contribution sequence ID", "description": "Credentialed SSE emits event: verification with ProgressEvent JSON, monotonically increasing id and heartbeat comments. Reconnect with Last-Event-ID; after is a page reload cursor. GET contribution detail is the polling fallback. No lease secret appears in events. Alternatively use a Redline API key with tuning:read. Bearer requests omit cookies, Origin and CSRF; all account, ownership, credit and version checks still apply.", "x-permission": "verified_customer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Last-Event-ID", "in": "header", "schema": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$" } }, { "name": "after", "in": "query", "schema": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$" } } ], "responses": { "200": { "description": "Persistent owned progress events; no invented completion percentage.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "id: 1\nevent: verification\ndata: {\"contractVersion\":\"1\",\"contributionId\":\"10000000-0000-4000-8000-000000000001\",\"itemId\":\"10000000-0000-4000-8000-000000000002\",\"jobId\":\"10000000-0000-4000-8000-000000000003\",\"sequence\":\"1\",\"stage\":\"queued\",\"itemState\":\"queued\",\"jobState\":\"queued\",\"message\":\"Queued for verification.\",\"occurredAt\":\"2026-09-17T00:00:00.000Z\"}\n\n" } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Structured authorization, stale state, dependency, disabled-feature or capacity failure.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-role": "customer", "tags": [ "Contributions" ], "security": [ { "tuningSession": [] }, { "RedlineApiKey": [] } ], "x-api-key-permission": "tuning:read" } }, "/forum/config": { "get": { "operationId": "forumConfiguration", "summary": "Configuration", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "topics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 40 }, "label": { "type": "string", "maxLength": 255 } }, "required": [ "id", "label" ], "additionalProperties": false } }, "entityTypes": { "type": "array", "items": { "type": "string", "maxLength": 40 } }, "limits": { "type": "object", "properties": { "title": { "type": "integer", "minimum": 0 }, "threadBody": { "type": "integer", "minimum": 0 }, "replyBody": { "type": "integer", "minimum": 0 }, "commentBody": { "type": "integer", "minimum": 0 }, "entities": { "type": "integer", "minimum": 0 }, "tags": { "type": "integer", "minimum": 0 }, "attachmentBytes": { "type": "integer", "minimum": 0 }, "attachments": { "type": "integer", "minimum": 0 } }, "required": [ "title", "threadBody", "replyBody", "commentBody", "entities", "tags", "attachmentBytes", "attachments" ], "additionalProperties": false }, "reputation": { "type": "object", "properties": { "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswer": { "type": "integer", "minimum": 0 }, "grantsDownloadCredits": { "type": "boolean" } }, "required": [ "helpful", "acceptedAnswer", "grantsDownloadCredits" ], "additionalProperties": false } }, "required": [ "enabled", "topics", "entityTypes", "limits", "reputation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "enabled": false, "topics": [], "entityTypes": [], "limits": { "title": 0, "threadBody": 0, "replyBody": 0, "commentBody": 0, "entities": 0, "tags": 0, "attachmentBytes": 0, "attachments": 0 }, "reputation": { "helpful": 0, "acceptedAnswer": 0, "grantsDownloadCredits": false } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/threads": { "get": { "operationId": "forumListThreads", "summary": "List Threads", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "view", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "sort", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "status", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "topic", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "entityId", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "fileId", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "author", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "ecuManufacturer", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "ecuFamily", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "softwareId", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "calibrationId", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "hardwareId", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "vehicleMake", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "vehicleModel", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "engine", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "from", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "to", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "hasFile", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "hasA2L", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForumThread" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] }, "post": { "operationId": "forumCreateThread", "summary": "Create Thread", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumCreateThread" }, "example": { "title": "Examplex", "body": "Examplexxxxxxxxxxxxx", "topic": "reverse-engineering" } } } }, "responses": { "201": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/threads/{id}": { "get": { "operationId": "forumReadThread", "summary": "Read Thread", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "pageSize", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "postId", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "includeDeleted", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumThreadDetail" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "title": "Example", "body": "Example", "replies": [], "repliesPage": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] }, "patch": { "operationId": "forumEditThread", "summary": "Edit Thread", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumEditThread" }, "example": { "title": "Examplex", "body": "Examplexxxxxxxxxxxxx", "topic": "reverse-engineering" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] }, "delete": { "operationId": "forumRemoveThread", "summary": "Remove Thread", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/replies/{id}": { "delete": { "operationId": "forumRemoveReply", "summary": "Remove Reply", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] }, "patch": { "operationId": "forumEditReply", "summary": "Edit Reply", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumEditPost" }, "example": { "body": "Example" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/comments/{id}": { "delete": { "operationId": "forumRemoveComment", "summary": "Remove Comment", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] }, "patch": { "operationId": "forumEditComment", "summary": "Edit Comment", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumEditComment" }, "example": { "body": "Example" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/threads/{id}/replies": { "get": { "operationId": "forumListReplies", "summary": "List Replies", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "postId", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForumPost" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] }, "post": { "operationId": "forumCreateReplies", "summary": "Create Replies", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumCreatePost" }, "example": { "body": "Example" } } } }, "responses": { "201": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/entities/{id}/comments": { "get": { "operationId": "forumListComments", "summary": "List Comments", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "postId", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForumPost" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] }, "post": { "operationId": "forumCreateComments", "summary": "Create Comments", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForumCreateComment" }, "example": { "body": "Example" } } } }, "responses": { "201": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/threads/{id}/solution": { "put": { "operationId": "forumSetSolution", "summary": "Set Solution", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "replyId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "replyId" ], "additionalProperties": false }, "example": { "replyId": "11111111-1111-4111-8111-111111111111" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/threads/{id}/entities": { "get": { "operationId": "forumThreadContext", "summary": "Thread Context", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForumEntity" } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] }, "put": { "operationId": "forumEditContext", "summary": "Edit Context", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "value": { "type": "string", "maxLength": 255 }, "sourceId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false } }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "entities" ], "additionalProperties": false }, "example": { "entities": [] } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/context": { "get": { "operationId": "forumFindContext", "summary": "Find Context", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "fileId", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "name": "type", "in": "query", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 180 }, "kind": { "type": "string", "maxLength": 40 }, "href": { "type": "string", "maxLength": 500 }, "identity": { "$ref": "#/components/schemas/CatalogueIdentity" } }, "required": [ "id", "title", "kind", "href", "identity" ], "additionalProperties": false }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "maxLength": 40 }, "sourceId": { "type": "string", "format": "uuid" }, "value": { "type": "string", "maxLength": 255 }, "required": { "type": "boolean" } }, "required": [ "type", "value" ], "additionalProperties": false } } }, "required": [ "file", "suggestions" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "maxLength": 40 }, "label": { "type": "string", "maxLength": 255 }, "input": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "value": { "type": "string", "maxLength": 255 }, "sourceId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "href": { "type": "string", "maxLength": 500 }, "source": { "type": "string", "maxLength": 40 }, "fileId": { "type": [ "string", "null" ] } }, "required": [ "type", "label", "input" ], "additionalProperties": false } } ] } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "file": { "id": "11111111-1111-4111-8111-111111111111", "title": "Example", "kind": "Example", "href": "Example", "identity": { "make": "Example", "model": "Example", "ecuFamily": "Example", "ecuFamilySource": "Example", "identifiers": [], "metadata": [], "canonicalSlug": "Example", "vehicleIdentityStatus": "verified_fitment", "vehicleIdentitySource": "Example" } }, "suggestions": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/entities": { "get": { "operationId": "forumListEntities", "summary": "List Entities", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "type", "in": "query", "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForumEntity" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] }, "post": { "operationId": "forumResolveEntity", "summary": "Resolve Entity", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "value": { "type": "string", "maxLength": 255 }, "sourceId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumEntity" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "type": "ecu_manufacturer", "label": "Example", "href": "Example", "source": "catalogue" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/entities/{id}": { "get": { "operationId": "forumReadEntity", "summary": "Read Entity", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumEntity" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "type": "ecu_manufacturer", "label": "Example", "href": "Example", "source": "catalogue" } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/entities/{id}/threads": { "get": { "operationId": "forumEntityThreads", "summary": "Entity Threads", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForumThread" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/files/{id}/discussions": { "get": { "operationId": "forumFileDiscussions", "summary": "File Discussions", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "context": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 180 }, "kind": { "type": "string", "maxLength": 40 }, "href": { "type": "string", "maxLength": 500 }, "identity": { "$ref": "#/components/schemas/CatalogueIdentity" } }, "required": [ "id", "title", "kind", "href", "identity" ], "additionalProperties": false }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "maxLength": 40 }, "sourceId": { "type": "string", "format": "uuid" }, "value": { "type": "string", "maxLength": 255 }, "required": { "type": "boolean" } }, "required": [ "type", "value" ], "additionalProperties": false } } }, "required": [ "file", "suggestions" ], "additionalProperties": false }, "entity": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "label": { "type": "string", "maxLength": 255 }, "fileId": { "type": [ "string", "null" ], "format": "uuid" }, "href": { "type": "string", "maxLength": 500 }, "source": { "enum": [ "catalogue", "discussion_context" ] }, "threadCount": { "type": "integer", "minimum": 0 }, "commentCount": { "type": "integer", "minimum": 0 }, "following": { "type": "boolean" }, "followId": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "id", "type", "label", "href", "source" ], "additionalProperties": false }, { "type": "null" } ] }, "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ForumThread" } }, "threadsPage": { "$ref": "#/components/schemas/Page" }, "commentCount": { "type": "integer", "minimum": 0 } }, "required": [ "context", "entity", "threads", "threadsPage", "commentCount" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "context": { "file": { "id": "11111111-1111-4111-8111-111111111111", "title": "Example", "kind": "Example", "href": "Example", "identity": { "make": "Example", "model": "Example", "ecuFamily": "Example", "ecuFamilySource": "Example", "identifiers": [], "metadata": [], "canonicalSlug": "Example", "vehicleIdentityStatus": "verified_fitment", "vehicleIdentitySource": "Example" } }, "suggestions": [] }, "entity": { "id": "11111111-1111-4111-8111-111111111111", "type": "ecu_manufacturer", "label": "Example", "href": "Example", "source": "catalogue" }, "threads": [], "threadsPage": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false }, "commentCount": 0 } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/{type}/{id}/reactions": { "post": { "operationId": "forumHelpful", "summary": "Helpful", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] }, "delete": { "operationId": "forumRemoveHelpful", "summary": "Remove Helpful", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/follows": { "post": { "operationId": "forumFollow", "summary": "Follow", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "threadId": { "type": "string", "format": "uuid" }, "entityId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/follows/{id}": { "delete": { "operationId": "forumUnfollow", "summary": "Unfollow", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/following": { "get": { "operationId": "forumFollowing", "summary": "Following", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "threadId": { "type": [ "string", "null" ] }, "entityId": { "type": [ "string", "null" ] }, "title": { "type": "string", "maxLength": 255 }, "slug": { "type": [ "string", "null" ] }, "href": { "type": "string", "maxLength": 500 }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "threadId", "entityId", "title", "slug", "href", "createdAt" ], "additionalProperties": false } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/forum/reports": { "post": { "operationId": "forumReport", "summary": "Report", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetType": { "enum": [ "thread", "reply", "comment" ] }, "targetId": { "type": "string", "format": "uuid" }, "reason": { "enum": [ "spam", "abuse", "copyright", "unsafe_content", "wrong_context", "other" ] }, "details": { "type": "string", "maxLength": 2000 } }, "required": [ "targetType", "targetId", "reason" ], "additionalProperties": false }, "example": { "targetType": "thread", "targetId": "11111111-1111-4111-8111-111111111111", "reason": "spam" } } } }, "responses": { "202": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/members": { "get": { "operationId": "forumFindMembers", "summary": "Find Members", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 60 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": [] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/members/{handle}": { "get": { "operationId": "forumMemberProfile", "summary": "Member Profile", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "handle": "Example", "reputation": 0 } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/me/profile": { "get": { "operationId": "forumMyProfile", "summary": "My Profile", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "displayName": "Example", "handle": "Example", "reputation": 0 } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] }, "patch": { "operationId": "forumEditProfile", "summary": "Edit Profile", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "maxLength": 32 }, "bio": { "type": "string", "maxLength": 500 } }, "required": [ "handle" ], "additionalProperties": false }, "example": { "handle": "Example" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/notifications": { "get": { "operationId": "forumNotifications", "summary": "Notifications", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "unread", "in": "query", "schema": { "type": "string", "maxLength": 5 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ForumNotification" } }, "page": { "$ref": "#/components/schemas/Page" }, "unreadCount": { "type": "integer", "minimum": 0 } }, "required": [ "data", "page", "unreadCount" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false }, "unreadCount": 0 } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/forum/notifications/read": { "patch": { "operationId": "forumReadNotifications", "summary": "Read Notifications", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail. Read state is monotonic and idempotent: this endpoint only marks the caller’s notifications read, so it has no If-Match or Idempotency-Key requirement.", "parameters": [ { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 100 }, "all": { "type": "boolean" } }, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/attachments": { "post": { "operationId": "forumUploadAttachment", "summary": "Upload Attachment", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "metadata": { "type": "string", "const": "{}" } }, "required": [ "file", "metadata" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 160 }, "mimeType": { "type": "string", "maxLength": 100 }, "byteSize": { "type": "integer", "minimum": 0 }, "path": { "type": "string", "maxLength": 200 } }, "required": [ "id", "filename", "mimeType", "byteSize" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "id": "11111111-1111-4111-8111-111111111111", "filename": "Example", "mimeType": "Example", "byteSize": 0 } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/attachments/{id}": { "get": { "operationId": "forumDownloadAttachment", "summary": "Download Attachment", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Correlates this request with sanitized tuning logs." }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." }, "Content-Disposition": { "schema": { "type": "string", "minLength": 1, "maxLength": 1024 }, "description": "Sanitized attachment filename plus UTF-8 filename*." }, "Content-Length": { "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "Exact stored byte count." }, "X-Content-Type-Options": { "schema": { "type": "string", "const": "nosniff" } }, "X-Redline-DME-Role": { "description": "Optional allowlisted DME side for this exact authorized version; no sibling or set identity.", "schema": { "type": "string", "enum": [ "single", "master", "slave" ] } }, "X-Redline-File-Role": { "description": "Optional allowlisted role for this exact authorized version.", "schema": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] }, "delete": { "operationId": "forumRemoveAttachment", "summary": "Remove Attachment", "tags": [ "Forum" ], "x-role": "customer", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [], "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/analytics": { "post": { "operationId": "forumRecordEvent", "summary": "Record Event", "tags": [ "Forum" ], "x-role": "public", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "maxLength": 40 }, "threadId": { "type": "string", "format": "uuid" }, "fileId": { "type": "string", "format": "uuid" }, "query": { "type": "string", "maxLength": 120 } }, "required": [ "event" ], "additionalProperties": false }, "example": { "event": "Example" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/forum/moderation/reports": { "get": { "operationId": "forumModerationReports", "summary": "Moderation Reports", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "status", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "reason", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "user", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "type", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "from", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "to", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "targetType": { "type": "string", "maxLength": 20 }, "targetId": { "type": "string", "format": "uuid" }, "threadId": { "type": [ "string", "null" ] }, "entityId": { "type": [ "string", "null" ] }, "title": { "type": "string", "maxLength": 255 }, "reason": { "type": "string", "maxLength": 40 }, "details": { "type": "string", "maxLength": 2000 }, "reporter": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "author": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "status": { "type": "string", "maxLength": 20 }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "etag": { "type": "string", "maxLength": 30 } }, "required": [ "id", "targetType", "targetId", "threadId", "entityId", "title", "reason", "details", "reporter", "author", "status", "createdAt", "etag" ], "additionalProperties": false } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/forum/moderation/reports/{id}": { "patch": { "operationId": "forumReviewReport", "summary": "Review Report", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "resolved", "dismissed", "open" ] }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "status", "reason" ], "additionalProperties": false }, "example": { "status": "resolved", "reason": "Example" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/moderation/content": { "get": { "operationId": "forumModerationContent", "summary": "Moderation Content", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "view", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "type", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "user", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "from", "in": "query", "schema": { "type": "string", "maxLength": 180 } }, { "name": "to", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ForumThread" }, { "$ref": "#/components/schemas/ForumPost" } ] } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/forum/moderation/{type}/{id}/actions": { "post": { "operationId": "forumModerate", "summary": "Moderate", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "pin", "unpin", "lock", "unlock", "archive", "unarchive", "delete", "restore", "topic", "relink" ] }, "reason": { "type": "string", "maxLength": 500 }, "topic": { "type": "string", "maxLength": 40 }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "value": { "type": "string", "maxLength": 255 }, "sourceId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false } } }, "required": [ "action", "reason" ], "additionalProperties": false }, "example": { "action": "pin", "reason": "Example" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/moderation/history": { "get": { "operationId": "forumAuditTrail", "summary": "Audit Trail", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "targetId", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "actorId": { "type": "string", "format": "uuid" }, "actor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "action": { "type": "string", "maxLength": 40 }, "targetType": { "type": "string", "maxLength": 30 }, "targetId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 500 }, "previousValue": { "type": [ "object", "null" ] }, "newValue": { "type": [ "object", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "actorId", "actor", "action", "targetType", "targetId", "reason", "previousValue", "newValue", "createdAt" ], "additionalProperties": false } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/forum/moderation/{type}/{id}/revisions": { "get": { "operationId": "forumRevisions", "summary": "Revisions", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "actorId": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "body": { "type": "string", "maxLength": 30000 }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "actorId", "title", "body", "reason", "createdAt" ], "additionalProperties": false } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "example": { "data": [], "page": { "page": 1, "pageSize": 25, "totalItems": 0, "totalPages": 0, "hasNextPage": false } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/forum/moderation/users/{id}/sanction": { "post": { "operationId": "forumPostingRestriction", "summary": "Posting Restriction", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/Csrf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "enum": [ "suspend", "ban", "restore" ] }, "days": { "type": "integer", "minimum": 1, "maximum": 30 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "action", "reason" ], "additionalProperties": false }, "example": { "action": "suspend", "reason": "Example" } } } }, "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ForumChange" } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": {} } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [], "csrfToken": [] } ] } }, "/forum/moderation/analytics": { "get": { "operationId": "forumActivity", "summary": "Activity", "tags": [ "Forum" ], "x-role": "editor", "description": "Forum Phases 1 and 2. Requires TUNING_FORUM_ENABLED=true except capability configuration. Reads only expose currently public linked context. Writes require a verified browser session and current permissions; developer keys cannot post or moderate. Reputation never grants download credits. Deletion is soft; moderation retains revisions and an audit trail.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "string", "maxLength": 180 } } ], "responses": { "200": { "description": "Forum operation completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "events": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string", "maxLength": 40 }, "count": { "type": "string", "maxLength": 30 } }, "required": [ "event", "count" ], "additionalProperties": false } } }, "required": [ "days", "events" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "example": { "data": { "days": 0, "events": [] } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" }, "description": "Never cache personal state or file bytes." } } }, "default": { "description": "Authorization, current-state, concurrency, validation or service failure; no credentials or internal exception details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "tuningSession": [] } ] } }, "/stripe/webhook": { "post": { "operationId": "receivePurchaseEvent", "summary": "Durably receive a signed tuning purchase notification", "tags": [ "Credits" ], "x-role": "provider", "description": "Mode-matched snapshot events pinned to 2024-11-20.acacia. The exact uncompressed application/json bytes (maximum 65536 bytes) must be signed. This endpoint precedes generic JSON parsing and browser security. A 200 confirms durable minimal receipt only; the separate leased processor confirms payment or reconciles minimal refund/dispute facts under the order's immutable versioned policy. Recovery never initiates a cash refund. Live configuration is separately gated and defaults off; no browser action or synchronous fulfillment.", "security": [ { "stripeWebhookSignature": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "object", "api_version", "livemode", "type", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[A-Za-z0-9]+$", "maxLength": 255 }, "object": { "const": "event" }, "api_version": { "const": "2024-11-20.acacia" }, "livemode": { "type": "boolean" }, "type": { "type": "string", "maxLength": 160 }, "data": { "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object" } } } } } } } }, "responses": { "200": { "description": "Durable receipt (including an explicitly recorded unsupported-event exception); not a credit-grant acknowledgment.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "received" ], "properties": { "received": { "const": true } } }, "example": { "received": true } } } }, "400": { "description": "Invalid signature, envelope, version, mode, merchant or body.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "409": { "description": "Conflicting permanent event identity; original facts retained and conflict audited.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "413": { "description": "Raw body exceeds 65536 bytes.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "503": { "description": "Disabled/unconfigured or durable receipt could not be confirmed. Retry the same event.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "stripeWebhookSignature": { "type": "apiKey", "in": "header", "name": "Stripe-Signature", "description": "Stripe HMAC over original bounded bytes with the dedicated tuning endpoint secret; 300-second absolute timestamp tolerance. Browser cookies, CSRF and API keys do not authorize this operation." }, "RedlineApiKey": { "type": "http", "scheme": "bearer", "description": "Account-issued rla_ key. Use only documented customer operations; never combine with cookies. Every active key includes UDS evidence submission." }, "tuningSession": { "type": "apiKey", "in": "cookie", "name": "__Host-redline_tuning_session", "description": "Opaque host-only Secure HttpOnly cookie. Never store in localStorage. Development uses redline_tuning_session_local on localhost only." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Stable session-bound CSRF issued by login/session; authenticated unsafe methods also validate Origin." } }, "parameters": { "Origin": { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri", "example": "https://redlineautohaus.com" }, "description": "Exact approved frontend origin. SameSite cookies alone do not protect sibling subdomains." }, "Csrf": { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Stable session-bound token from login or GET /auth/session. Required on authenticated unsafe requests." }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "description": "Current resource ETag. Version-link/review edits use the owning version ETag; revision uploads and publish use the file ETag. Missing:428; stale:412." }, "Idempotency": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$", "example": "example-operation-20260917-001" }, "description": "Actor/operation-scoped key, retained 24h. Identical replay returns the original business result; changed metadata, filename or byte hash returns409." } }, "schemas": { "CheckoutSelection": { "type": "object", "additionalProperties": false, "required": [ "packKey", "catalogueRevision", "attemptKey" ], "properties": { "packKey": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "catalogueRevision": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "attemptKey": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } } }, "PurchasePackPublic": { "type": "object", "additionalProperties": false, "required": [ "key", "credits", "priceMinor", "discountPercent" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "credits": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "priceMinor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "discountPercent": { "anyOf": [ { "type": "integer", "enum": [ 0, 10, 20 ] }, { "type": "null" } ] } } }, "PurchaseCataloguePublic": { "type": "object", "additionalProperties": false, "required": [ "revision", "currency", "minorUnitExponent", "taxBehavior", "syntheticTest", "approvedPolicy", "taxTreatment", "termsRevision", "packs" ], "properties": { "revision": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, "currency": { "type": "string", "enum": [ "usd", "cad", "eur", "gbp", "jpy", "isk", "ugx" ] }, "minorUnitExponent": { "type": "integer", "enum": [ 0, 2 ] }, "taxBehavior": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "syntheticTest": { "type": "boolean" }, "approvedPolicy": { "type": "boolean" }, "taxTreatment": { "type": "string", "enum": [ "legacy", "provider_calculated_inclusive", "fixed_gross_merchant_accounted" ], "description": "Immutable tax presentation: retained legacy, provider-calculated tax included in the gross total, or fixed gross with any applicable tax accounted for by the merchant outside Checkout." }, "termsRevision": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" }, { "type": "null" } ] }, "packs": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "$ref": "#/components/schemas/PurchasePackPublic" } } } }, "CheckoutPacks": { "type": "object", "additionalProperties": false, "required": [ "purchaseEnabled", "catalogue" ], "properties": { "purchaseEnabled": { "type": "boolean" }, "catalogue": { "anyOf": [ { "$ref": "#/components/schemas/PurchaseCataloguePublic" }, { "type": "null" } ] } } }, "PurchaserOrder": { "type": "object", "additionalProperties": false, "required": [ "id", "credits", "currency", "subtotalMinor", "taxMinor", "includedTaxMinor", "totalMinor", "taxBehavior", "taxTreatment", "approvedRecoveryPolicy", "paymentState", "recoveryState", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "credits": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "currency": { "type": "string", "enum": [ "usd", "cad", "eur", "gbp", "jpy", "isk", "ugx" ] }, "subtotalMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$" }, "taxMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "description": "Application-added tax in minor units. Inclusive catalogues keep this at zero." }, "includedTaxMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$" }, { "type": "null" } ], "example": null, "description": "Provider-confirmed calculated tax included within the immutable advertised total. Null before proof, for retained legacy history, and for fixed-gross merchant-accounted orders whose included portion is intentionally unknown." }, "totalMinor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "taxBehavior": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "taxTreatment": { "type": "string", "enum": [ "legacy", "provider_calculated_inclusive", "fixed_gross_merchant_accounted" ], "description": "Immutable tax presentation: retained legacy, provider-calculated tax included in the gross total, or fixed gross with any applicable tax accounted for by the merchant outside Checkout." }, "approvedRecoveryPolicy": { "type": "boolean" }, "paymentState": { "type": "string", "enum": [ "created", "checkout_pending", "payment_pending", "paid", "failed", "cancelled", "expired", "exception" ] }, "recoveryState": { "type": "string", "enum": [ "none", "pending", "partial", "full", "disputed", "exception" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "CheckoutOrder": { "type": "object", "additionalProperties": false, "required": [ "id", "credits", "currency", "subtotalMinor", "taxMinor", "includedTaxMinor", "totalMinor", "taxBehavior", "taxTreatment", "approvedRecoveryPolicy", "paymentState", "recoveryState", "createdAt", "checkout" ], "properties": { "id": { "type": "string", "format": "uuid" }, "credits": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" }, "currency": { "type": "string", "enum": [ "usd", "cad", "eur", "gbp", "jpy", "isk", "ugx" ] }, "subtotalMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$" }, "taxMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$", "description": "Application-added tax in minor units. Inclusive catalogues keep this at zero." }, "includedTaxMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,11})$" }, { "type": "null" } ], "example": null, "description": "Provider-confirmed calculated tax included within the immutable advertised total. Null before proof, for retained legacy history, and for fixed-gross merchant-accounted orders whose included portion is intentionally unknown." }, "totalMinor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "taxBehavior": { "type": "string", "enum": [ "inclusive", "exclusive" ] }, "taxTreatment": { "type": "string", "enum": [ "legacy", "provider_calculated_inclusive", "fixed_gross_merchant_accounted" ], "description": "Immutable tax presentation: retained legacy, provider-calculated tax included in the gross total, or fixed gross with any applicable tax accounted for by the merchant outside Checkout." }, "approvedRecoveryPolicy": { "type": "boolean" }, "paymentState": { "type": "string", "enum": [ "created", "checkout_pending", "payment_pending", "paid", "failed", "cancelled", "expired", "exception" ] }, "recoveryState": { "type": "string", "enum": [ "none", "pending", "partial", "full", "disputed", "exception" ] }, "createdAt": { "type": "string", "format": "date-time" }, "checkout": { "type": "object", "additionalProperties": false, "required": [ "state", "url", "expiresAt" ], "properties": { "state": { "type": "string", "enum": [ "pending", "open", "completed", "expired", "exception" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } } } }, "PurchaseResolutionSelection": { "type": "object", "additionalProperties": false, "required": [ "inboxId", "reason" ], "properties": { "inboxId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Required staff reason without credentials or customer details. Null inboxId selects a server-located order proof; no signed event is fabricated." } } }, "PurchaseResolutionResult": { "type": "object", "additionalProperties": false, "required": [ "operationId", "orderId", "inboxId", "source", "state", "executions", "code" ], "properties": { "operationId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string", "format": "uuid" }, "inboxId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "source": { "enum": [ "signed_receipt", "order_probe" ] }, "state": { "enum": [ "processing", "completed", "exception" ] }, "executions": { "type": "integer", "minimum": 1, "maximum": 3 }, "code": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] } } }, "PurchaseReconciliationSummary": { "type": "object", "additionalProperties": false, "required": [ "orderId", "paymentState", "recoveryState" ], "properties": { "orderId": { "type": "string", "format": "uuid" }, "paymentState": { "type": "string", "maxLength": 80 }, "recoveryState": { "type": "string", "maxLength": 80 } } }, "PurchaseReconciliation": { "type": "object", "additionalProperties": false, "required": [ "orderId", "paymentState", "recoveryState", "credits", "netCredits", "expectedNetCredits", "wallet", "findings", "providerProof", "receipts", "operations", "etag" ], "properties": { "orderId": { "type": "string", "format": "uuid" }, "paymentState": { "type": "string", "maxLength": 80 }, "recoveryState": { "type": "string", "maxLength": 80 }, "credits": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "netCredits": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "expectedNetCredits": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ] }, "wallet": { "type": "object", "additionalProperties": false, "required": [ "balance", "ledgerSum", "restriction", "purchaseHolds", "complete" ], "properties": { "balance": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "ledgerSum": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "restriction": { "enum": [ "none", "review_hold" ] }, "purchaseHolds": { "type": "integer", "minimum": 0 }, "complete": { "type": "boolean" } } }, "findings": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 32 }, "providerProof": { "enum": [ "not_read", "confirmed_paid", "confirmed_nonpaid", "mismatch_or_unavailable" ] }, "receipts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "state", "attempts", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "maxLength": 80 }, "attempts": { "type": "integer", "minimum": 0 }, "code": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] } } }, "maxItems": 100 }, "operations": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "inboxId", "source", "state", "executions", "code" ], "properties": { "id": { "type": "string", "format": "uuid" }, "inboxId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "source": { "enum": [ "signed_receipt", "order_probe" ] }, "state": { "type": "string", "maxLength": 80 }, "executions": { "type": "integer", "minimum": 0 }, "code": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] } } }, "maxItems": 500 }, "etag": { "type": "string", "pattern": "^\"[a-f0-9]{64}\"$", "example": "\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"" } } }, "PrivateCompanyVerification": { "type": "object", "additionalProperties": false, "required": [ "companyName", "status", "companyVerified" ], "properties": { "companyName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "unverified", "verified", "revoked" ] }, "companyVerified": { "type": "boolean" } }, "allOf": [ { "if": { "properties": { "companyVerified": { "const": true } } }, "then": { "properties": { "companyName": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" }, "status": { "const": "verified" } } } } ] }, "AdminCompanyVerification": { "type": "object", "additionalProperties": false, "required": [ "companyName", "status", "companyVerified", "userId", "companyNameSnapshot", "verifiedBy", "verifiedAt", "revokedBy", "revokedAt", "revocationReason", "internalNotes", "rowVersion", "etag" ], "allOf": [ { "if": { "properties": { "companyVerified": { "const": true } } }, "then": { "properties": { "companyName": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" }, "status": { "const": "verified" } } } }, { "if": { "properties": { "status": { "const": "unverified" } } }, "then": { "properties": { "companyNameSnapshot": { "type": "null" }, "verifiedBy": { "type": "null" }, "verifiedAt": { "type": "null" }, "revokedBy": { "type": "null" }, "revokedAt": { "type": "null" }, "revocationReason": { "type": "null" }, "internalNotes": { "type": "null" } } }, "else": { "properties": { "companyNameSnapshot": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" }, "verifiedBy": { "type": "string", "format": "uuid" }, "verifiedAt": { "type": "string", "format": "date-time" } } } }, { "if": { "properties": { "status": { "const": "revoked" } } }, "then": { "properties": { "revokedBy": { "type": "string", "format": "uuid" }, "revokedAt": { "type": "string", "format": "date-time" }, "revocationReason": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" } } }, "else": { "properties": { "revokedBy": { "type": "null" }, "revokedAt": { "type": "null" }, "revocationReason": { "type": "null" } } } } ], "properties": { "companyName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "unverified", "verified", "revoked" ] }, "companyVerified": { "type": "boolean" }, "userId": { "type": "string", "format": "uuid" }, "companyNameSnapshot": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" }, { "type": "null" } ] }, "verifiedBy": { "type": [ "string", "null" ], "format": "uuid" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedBy": { "type": [ "string", "null" ], "format": "uuid" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revocationReason": { "type": [ "string", "null" ], "maxLength": 1000 }, "internalNotes": { "type": [ "string", "null" ], "maxLength": 2000 }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } } }, "CompanyVerificationAction": { "type": "object", "additionalProperties": false, "required": [ "action", "reason" ], "properties": { "action": { "type": "string", "enum": [ "verify", "revoke" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "\\S" }, "internalNotes": { "type": [ "string", "null" ], "maxLength": 2000 } } }, "PublicCompanyAttribution": { "type": "object", "additionalProperties": false, "required": [ "companyName", "companyVerified" ], "properties": { "companyName": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "\\S" }, "companyVerified": { "type": "boolean" }, "evcLicense": { "type": "object", "additionalProperties": false, "required": [ "checkUrl", "imageUrl" ], "properties": { "checkUrl": { "type": "string", "format": "uri", "pattern": "^https://www\\.evc\\.de/en/check_evc_license\\.asp\\?k=" }, "imageUrl": { "type": "string", "format": "uri", "pattern": "^https://www\\.evc\\.de/common/check_evc_license_image\\.asp\\?k=" } } } } }, "Page": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalItems": { "type": "integer", "minimum": 0 }, "totalPages": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" } }, "required": [ "page", "pageSize", "totalItems", "totalPages", "hasNextPage" ], "additionalProperties": false }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri-reference" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "minLength": 1, "maxLength": 4000 }, "instance": { "type": "string", "format": "uri-reference" }, "code": { "type": "string", "minLength": 1, "maxLength": 100 }, "requestId": { "type": "string", "minLength": 1, "maxLength": 64 }, "fieldErrors": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "required": [ "type", "title", "status", "detail", "instance", "code", "requestId" ], "additionalProperties": false }, "EvcLicenseReference": { "type": "object", "properties": { "checkUrl": { "type": "string", "format": "uri", "pattern": "^https://www\\.evc\\.de/en/check_evc_license\\.asp\\?k=" }, "imageUrl": { "type": "string", "format": "uri", "pattern": "^https://www\\.evc\\.de/common/check_evc_license_image\\.asp\\?k=" } }, "required": [ "checkUrl", "imageUrl" ], "additionalProperties": false }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "email": { "type": "string", "minLength": 1, "maxLength": 254, "format": "email" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "companyName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "evcLicense": { "anyOf": [ { "$ref": "#/components/schemas/EvcLicenseReference" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "customer", "editor", "admin" ] }, "status": { "type": "string", "enum": [ "pending_verification", "active", "suspended" ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "lastLoginAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "email", "displayName", "companyName", "evcLicense", "phone", "role", "status", "emailVerifiedAt", "lastLoginAt", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "Permissions": { "type": "object", "properties": { "isStaff": { "type": "boolean" }, "canManageCatalog": { "type": "boolean" }, "canPublish": { "type": "boolean" }, "canManageUsers": { "type": "boolean" }, "canDownload": { "type": "boolean" } }, "required": [ "isStaff", "canManageCatalog", "canPublish", "canManageUsers", "canDownload" ], "additionalProperties": false }, "AuthSession": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "permissions": { "$ref": "#/components/schemas/Permissions" }, "csrfToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" } }, "required": [ "user", "permissions", "csrfToken", "expiresAt" ], "additionalProperties": false }, "Message": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "message" ], "additionalProperties": false }, "VerificationResult": { "type": "object", "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 500 }, "returnTo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8000 }, { "type": "null" } ] } }, "required": [ "message", "returnTo" ], "additionalProperties": false }, "SessionDevice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "lastSeenAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "idleExpiresAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "userAgent": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] }, "isCurrent": { "type": "boolean" } }, "required": [ "id", "createdAt", "lastSeenAt", "expiresAt", "idleExpiresAt", "revokedAt", "userAgent", "isCurrent" ], "additionalProperties": false }, "AccessDecision": { "type": "object", "properties": { "canDownload": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "SIGN_IN_REQUIRED", "EMAIL_VERIFICATION_REQUIRED", "ACCESS_REQUIRED", "PURCHASE_NOT_AVAILABLE", "FILE_UNAVAILABLE", "CREDIT_ENTITLEMENT_REQUIRED", "VERSION_WITHDRAWN", "DEPENDENCY_REVIEW_HOLD", "ALLOWED" ] } }, "required": [ "canDownload", "reason" ], "additionalProperties": false }, "DownloadEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "fileVersionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "outcome": { "type": "string", "enum": [ "started", "completed", "aborted", "failed" ] }, "bytesSent": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] } }, "required": [ "id", "fileId", "fileVersionId", "title", "versionLabel", "outcome", "bytesSent", "createdAt", "finishedAt" ], "additionalProperties": false }, "OwnGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "effectiveStatus": { "type": "string", "enum": [ "unavailable", "revoked", "expired", "active", "restricted" ] }, "access": { "$ref": "#/components/schemas/AccessDecision" } }, "required": [ "id", "fileId", "title", "reason", "expiresAt", "revokedAt", "effectiveStatus", "access" ], "additionalProperties": false }, "Grant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "userId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "grantedBy": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "userId", "fileId", "grantedBy", "reason", "expiresAt", "revokedAt", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "GrantWithTitle": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "userId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "grantedBy": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 } }, "required": [ "id", "userId", "fileId", "grantedBy", "reason", "expiresAt", "revokedAt", "createdAt", "updatedAt", "rowVersion", "etag", "title" ], "additionalProperties": false }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "actorUserId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "action": { "type": "string", "minLength": 1, "maxLength": 100 }, "entityType": { "type": "string", "minLength": 1, "maxLength": 60 }, "entityId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "requestId": { "type": "string", "minLength": 1, "maxLength": 64 }, "details": { "description": "Sanitized structured change summary; no credentials, tokens, file contents or unrestricted request bodies.", "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "number", "boolean", "array", "object", "null" ] } }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" } }, "required": [ "id", "actorUserId", "action", "entityType", "entityId", "requestId", "details", "createdAt" ], "additionalProperties": false }, "OpeningHours": { "type": "object", "properties": { "monday": { "anyOf": [ { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" }, "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00" } }, "required": [ "open", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "tuesday": { "anyOf": [ { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" }, "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00" } }, "required": [ "open", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "wednesday": { "anyOf": [ { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" }, "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00" } }, "required": [ "open", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "thursday": { "anyOf": [ { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" }, "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00" } }, "required": [ "open", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "friday": { "anyOf": [ { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" }, "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00" } }, "required": [ "open", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "saturday": { "anyOf": [ { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" }, "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00" } }, "required": [ "open", "close" ], "additionalProperties": false }, { "type": "null" } ] }, "sunday": { "anyOf": [ { "type": "object", "properties": { "open": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "08:00" }, "close": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "example": "18:00" } }, "required": [ "open", "close" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "additionalProperties": false }, "UploadLimits": { "type": "object", "properties": { "maxBinBytes": { "type": "integer", "minimum": 0, "default": 67108864 }, "maxA2lBytes": { "type": "integer", "minimum": 0, "default": 67108864 }, "maxDocumentBytes": { "type": "integer", "minimum": 0, "default": 10485760 }, "maxMultipartBytes": { "type": "integer", "minimum": 0, "default": 68157440 }, "maxMetadataBytes": { "type": "integer", "minimum": 0, "default": 65536 } }, "required": [ "maxBinBytes", "maxA2lBytes", "maxDocumentBytes", "maxMultipartBytes", "maxMetadataBytes" ], "additionalProperties": false }, "Site": { "type": "object", "properties": { "id": { "type": "integer", "const": 1 }, "branchName": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentName": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentUrl": { "type": "string", "minLength": 1, "maxLength": 255, "format": "uri" }, "publicEmail": { "type": "string", "minLength": 1, "maxLength": 254, "format": "email" }, "phoneDisplay": { "type": "string", "minLength": 1, "maxLength": 60 }, "phoneE164": { "type": "string", "minLength": 1, "maxLength": 30 }, "addressLine1": { "type": "string", "minLength": 1, "maxLength": 180 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20 }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 80 }, "openingHours": { "$ref": "#/components/schemas/OpeningHours" }, "identityStatement": { "type": "string", "minLength": 1, "maxLength": 500 }, "contactSourceUrl": { "type": "string", "minLength": 1, "maxLength": 500, "format": "uri" }, "contactsVerifiedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "purchaseEnabled": { "type": "boolean", "const": false }, "uploadLimits": { "$ref": "#/components/schemas/UploadLimits" } }, "required": [ "id", "branchName", "parentName", "parentUrl", "publicEmail", "phoneDisplay", "phoneE164", "addressLine1", "city", "region", "postalCode", "countryCode", "timezone", "openingHours", "identityStatement", "contactSourceUrl", "contactsVerifiedAt", "createdAt", "updatedAt", "rowVersion", "etag", "purchaseEnabled", "uploadLimits" ], "additionalProperties": false }, "AdminSite": { "type": "object", "properties": { "id": { "type": "integer", "const": 1 }, "branchName": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentName": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentUrl": { "type": "string", "minLength": 1, "maxLength": 255, "format": "uri" }, "publicEmail": { "type": "string", "minLength": 1, "maxLength": 254, "format": "email" }, "phoneDisplay": { "type": "string", "minLength": 1, "maxLength": 60 }, "phoneE164": { "type": "string", "minLength": 1, "maxLength": 30 }, "addressLine1": { "type": "string", "minLength": 1, "maxLength": 180 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20 }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 80 }, "openingHours": { "$ref": "#/components/schemas/OpeningHours" }, "identityStatement": { "type": "string", "minLength": 1, "maxLength": 500 }, "contactSourceUrl": { "type": "string", "minLength": 1, "maxLength": 500, "format": "uri" }, "contactsVerifiedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "purchaseEnabled": { "type": "boolean", "const": false }, "uploadLimits": { "$ref": "#/components/schemas/UploadLimits" }, "submissionsEnabled": { "type": "boolean" }, "aiResearchEnabled": { "type": "boolean" }, "automaticAcceptanceEnabled": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "type": "integer", "minimum": 1, "maximum": 100, "default": 90 }, "creditAcquisitionsEnabled": { "type": "boolean" }, "contributionRightsVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "contributionRightsText": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 12000 }, { "type": "null" } ] }, "activeCreditPolicyId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "canonicalBackfillCompletedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "effectiveAddonSwitches": { "type": "object", "properties": { "submissionsEnabled": { "type": "boolean" }, "aiResearchEnabled": { "type": "boolean" }, "automaticAcceptanceEnabled": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "type": "integer", "minimum": 1, "maximum": 100, "default": 90 }, "creditAcquisitionsEnabled": { "type": "boolean" } }, "required": [ "submissionsEnabled", "aiResearchEnabled", "automaticAcceptanceEnabled", "a2lChangedByteCoveragePercent", "creditAcquisitionsEnabled" ], "additionalProperties": false } }, "required": [ "id", "branchName", "parentName", "parentUrl", "publicEmail", "phoneDisplay", "phoneE164", "addressLine1", "city", "region", "postalCode", "countryCode", "timezone", "openingHours", "identityStatement", "contactSourceUrl", "contactsVerifiedAt", "createdAt", "updatedAt", "rowVersion", "etag", "purchaseEnabled", "uploadLimits", "submissionsEnabled", "aiResearchEnabled", "automaticAcceptanceEnabled", "a2lChangedByteCoveragePercent", "creditAcquisitionsEnabled", "contributionRightsVersion", "contributionRightsText", "activeCreditPolicyId", "canonicalBackfillCompletedAt", "effectiveAddonSwitches" ], "additionalProperties": false }, "SitePatch": { "type": "object", "properties": { "branchName": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentName": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentUrl": { "type": "string", "minLength": 1, "maxLength": 255, "format": "uri" }, "publicEmail": { "type": "string", "minLength": 1, "maxLength": 254, "format": "email" }, "phoneDisplay": { "type": "string", "minLength": 1, "maxLength": 60 }, "phoneE164": { "type": "string", "minLength": 1, "maxLength": 30 }, "addressLine1": { "type": "string", "minLength": 1, "maxLength": 180 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20 }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "timezone": { "type": "string", "minLength": 1, "maxLength": 80 }, "openingHours": { "$ref": "#/components/schemas/OpeningHours" }, "identityStatement": { "type": "string", "minLength": 1, "maxLength": 500 }, "contactSourceUrl": { "type": "string", "minLength": 1, "maxLength": 500, "format": "uri" }, "contactsVerifiedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "submissionsEnabled": { "type": "boolean" }, "aiResearchEnabled": { "type": "boolean" }, "automaticAcceptanceEnabled": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "type": "integer", "minimum": 1, "maximum": 100, "default": 90 }, "creditAcquisitionsEnabled": { "type": "boolean" }, "contributionRightsVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "contributionRightsText": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 12000 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "VehicleMake": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "name", "slug", "isActive", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "VehicleMakeCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" } }, "required": [ "name", "slug" ], "additionalProperties": false }, "VehicleMakePatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "VehicleModel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "makeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "makeId", "name", "slug", "isActive", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "VehicleModelCreate": { "type": "object", "properties": { "makeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" } }, "required": [ "makeId", "name", "slug" ], "additionalProperties": false }, "VehicleModelPatch": { "type": "object", "properties": { "makeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "VehicleVariant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "modelId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "variantKey": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "generation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "engineCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "fuelType": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "transmission": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "displacementCc": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000 }, { "type": "null" } ] }, "powerKw": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{1,6}(\\.[0-9]{1,2})?$", "example": "150.00" }, { "type": "null" } ] }, "yearFrom": { "anyOf": [ { "type": "integer", "minimum": 1886, "maximum": 2200 }, { "type": "null" } ] }, "yearTo": { "anyOf": [ { "type": "integer", "minimum": 1886, "maximum": 2200 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "modelId", "variantKey", "name", "generation", "engineCode", "fuelType", "transmission", "displacementCc", "powerKw", "yearFrom", "yearTo", "market", "isActive", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "VehicleVariantCreate": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "variantKey": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "generation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "engineCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "fuelType": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "transmission": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "displacementCc": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000 }, { "type": "null" } ] }, "powerKw": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{1,6}(\\.[0-9]{1,2})?$", "example": "150.00" }, { "type": "number", "minimum": 0, "maximum": 999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "yearFrom": { "anyOf": [ { "type": "integer", "minimum": 1886, "maximum": 2200 }, { "type": "null" } ] }, "yearTo": { "anyOf": [ { "type": "integer", "minimum": 1886, "maximum": 2200 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "modelId", "variantKey", "name" ], "additionalProperties": false }, "VehicleVariantPatch": { "type": "object", "properties": { "modelId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "variantKey": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "generation": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "engineCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "fuelType": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "transmission": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "displacementCc": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100000 }, { "type": "null" } ] }, "powerKw": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{1,6}(\\.[0-9]{1,2})?$", "example": "150.00" }, { "type": "number", "minimum": 0, "maximum": 999999.99, "multipleOf": 0.01 }, { "type": "null" } ] }, "yearFrom": { "anyOf": [ { "type": "integer", "minimum": 1886, "maximum": 2200 }, { "type": "null" } ] }, "yearTo": { "anyOf": [ { "type": "integer", "minimum": 1886, "maximum": 2200 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "EcuManufacturer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "name", "slug", "isActive", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "EcuManufacturerCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" } }, "required": [ "name", "slug" ], "additionalProperties": false }, "EcuManufacturerPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "slug": { "type": "string", "minLength": 1, "maxLength": 120 }, "isActive": { "type": "boolean" } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "EcuType": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "manufacturerId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 1, "maxLength": 140 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "processor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "controllerRole": { "type": "string", "enum": [ "engine", "transmission", "other" ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "manufacturerId", "name", "slug", "family", "processor", "controllerRole", "notes", "isActive", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "EcuTypeCreate": { "type": "object", "properties": { "manufacturerId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 1, "maxLength": 140 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "processor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "controllerRole": { "type": "string", "enum": [ "engine", "transmission", "other" ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "manufacturerId", "name", "slug" ], "additionalProperties": false }, "EcuTypePatch": { "type": "object", "properties": { "manufacturerId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "slug": { "type": "string", "minLength": 1, "maxLength": 140 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "processor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "controllerRole": { "type": "string", "enum": [ "engine", "transmission", "other" ] }, "notes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "IdentifierInput": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "isPrimary": { "type": "boolean" }, "source": { "type": "string", "enum": [ "manual", "flasher_report", "a2l", "bin_extractor" ] }, "sourceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue" ], "additionalProperties": false }, "Identifier": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "softwareReleaseId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "isPrimary": { "type": "boolean" }, "source": { "type": "string", "enum": [ "manual", "flasher_report", "a2l", "bin_extractor" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "softwareReleaseId", "kind", "namespace", "rawValue", "normalizedValue", "isPrimary", "source", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "StaffIdentifier": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "softwareReleaseId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "isPrimary": { "type": "boolean" }, "source": { "type": "string", "enum": [ "manual", "flasher_report", "a2l", "bin_extractor" ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "sourceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "id", "softwareReleaseId", "kind", "namespace", "rawValue", "normalizedValue", "isPrimary", "source", "createdAt", "updatedAt", "rowVersion", "etag", "sourceNote" ], "additionalProperties": false }, "Fitment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "vehicleVariantId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "status": { "type": "string", "enum": [ "candidate", "verified" ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "variant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "engineCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "yearFrom": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "yearTo": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "model": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "make": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "make" ], "additionalProperties": false } }, "required": [ "id", "name", "engineCode", "yearFrom", "yearTo", "model" ], "additionalProperties": false } }, "required": [ "id", "vehicleVariantId", "status", "etag", "variant" ], "additionalProperties": false }, "StaffFitment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "vehicleVariantId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "status": { "type": "string", "enum": [ "candidate", "verified" ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "variant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "engineCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "yearFrom": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "yearTo": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "model": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "make": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "make" ], "additionalProperties": false } }, "required": [ "id", "name", "engineCode", "yearFrom", "yearTo", "model" ], "additionalProperties": false }, "evidenceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "id", "vehicleVariantId", "status", "etag", "variant", "evidenceNote" ], "additionalProperties": false }, "SoftwareRelease": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "ecuTypeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 180 }, "identificationStatus": { "type": "string", "enum": [ "unverified", "verified" ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "ecu": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "manufacturer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "family", "manufacturer" ], "additionalProperties": false }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Identifier" } }, "fitments": { "type": "array", "items": { "$ref": "#/components/schemas/Fitment" } } }, "required": [ "id", "ecuTypeId", "displayName", "identificationStatus", "verifiedAt", "createdAt", "updatedAt", "rowVersion", "etag", "ecu", "identifiers", "fitments" ], "additionalProperties": false }, "StaffSoftwareRelease": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "ecuTypeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 180 }, "identificationStatus": { "type": "string", "enum": [ "unverified", "verified" ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "ecu": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "manufacturer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "family", "manufacturer" ], "additionalProperties": false }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/StaffIdentifier" } }, "fitments": { "type": "array", "items": { "$ref": "#/components/schemas/StaffFitment" } }, "createdBy": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "verifiedBy": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "verificationNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "id", "ecuTypeId", "displayName", "identificationStatus", "verifiedAt", "createdAt", "updatedAt", "rowVersion", "etag", "ecu", "identifiers", "fitments", "createdBy", "verifiedBy", "verificationNotes" ], "additionalProperties": false }, "VersionRelease": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "ecuTypeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 180 }, "identificationStatus": { "type": "string", "enum": [ "unverified", "verified" ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "ecu": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "manufacturer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "family", "manufacturer" ], "additionalProperties": false }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Identifier" } }, "fitments": { "type": "array", "items": { "$ref": "#/components/schemas/Fitment" } }, "matchStatus": { "type": "string", "enum": [ "candidate", "verified", "rejected" ] } }, "required": [ "id", "ecuTypeId", "displayName", "identificationStatus", "verifiedAt", "createdAt", "updatedAt", "rowVersion", "etag", "ecu", "identifiers", "fitments", "matchStatus" ], "additionalProperties": false }, "StaffVersionRelease": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "ecuTypeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 180 }, "identificationStatus": { "type": "string", "enum": [ "unverified", "verified" ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "ecu": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "manufacturer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "family", "manufacturer" ], "additionalProperties": false }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/StaffIdentifier" } }, "fitments": { "type": "array", "items": { "$ref": "#/components/schemas/StaffFitment" } }, "createdBy": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "verifiedBy": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "verificationNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "matchStatus": { "type": "string", "enum": [ "candidate", "verified", "rejected" ] }, "evidenceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "id", "ecuTypeId", "displayName", "identificationStatus", "verifiedAt", "createdAt", "updatedAt", "rowVersion", "etag", "ecu", "identifiers", "fitments", "createdBy", "verifiedBy", "verificationNotes", "matchStatus", "evidenceNote" ], "additionalProperties": false }, "ReleaseLinkInput": { "type": "object", "properties": { "softwareReleaseId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "matchStatus": { "type": "string", "enum": [ "candidate", "verified", "rejected" ] }, "evidenceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "softwareReleaseId" ], "additionalProperties": false }, "FitmentInput": { "type": "object", "properties": { "vehicleVariantId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "status": { "type": "string", "enum": [ "candidate", "verified" ] }, "evidenceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "vehicleVariantId" ], "additionalProperties": false }, "SoftwareReleaseCreate": { "type": "object", "properties": { "ecuTypeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 180 }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/IdentifierInput" }, "maxItems": 100 }, "identificationStatus": { "type": "string", "enum": [ "unverified", "verified" ] }, "verificationNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "ecuTypeId", "displayName", "identifiers" ], "additionalProperties": false }, "SoftwareReleasePatch": { "type": "object", "properties": { "ecuTypeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 180 }, "identificationStatus": { "type": "string", "enum": [ "unverified", "verified" ] }, "verificationNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "IdentifiersReplacement": { "type": "object", "properties": { "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/IdentifierInput" }, "maxItems": 100 } }, "required": [ "identifiers" ], "additionalProperties": false }, "FitmentsReplacement": { "type": "object", "properties": { "fitments": { "type": "array", "items": { "$ref": "#/components/schemas/FitmentInput" }, "maxItems": 100 } }, "required": [ "fitments" ], "additionalProperties": false }, "RelationInput": { "type": "object", "properties": { "targetVersionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "relationType": { "type": "string", "enum": [ "definition_for", "documentation_for" ] }, "status": { "type": "string", "enum": [ "candidate", "verified", "rejected" ] }, "evidenceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "targetVersionId", "relationType" ], "additionalProperties": false }, "VersionRelation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "sourceVersionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "targetVersionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "relationType": { "type": "string", "enum": [ "definition_for", "documentation_for" ] }, "status": { "type": "string", "enum": [ "candidate", "verified", "rejected" ] }, "evidenceNote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "verifiedBy": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" } }, "required": [ "id", "sourceVersionId", "targetVersionId", "relationType", "status", "evidenceNote", "verifiedBy", "verifiedAt", "createdAt", "updatedAt", "rowVersion", "etag" ], "additionalProperties": false }, "PublicDmeContext": { "type": "object", "properties": { "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "dmeRole", "fileRole" ], "additionalProperties": false }, "FileVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "versionNo": { "type": "integer", "minimum": 1 }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "originalFilename": { "type": "string", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 120 }, "stage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "publicNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "reviewState": { "type": "string", "enum": [ "draft", "ready", "rejected" ] }, "validatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "lockedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "lockReason": { "anyOf": [ { "type": "string", "enum": [ "publication", "baseline", "association" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "byteSize": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "releases": { "type": "array", "items": { "$ref": "#/components/schemas/VersionRelease" } }, "companyAttribution": { "$ref": "#/components/schemas/PublicCompanyAttribution" }, "dmeContext": { "$ref": "#/components/schemas/PublicDmeContext" } }, "required": [ "id", "fileId", "versionNo", "versionLabel", "originalFilename", "mimeType", "stage", "publicNotes", "readType", "readMethod", "readTool", "fuelRequirement", "hardwareRequirements", "reviewState", "validatedAt", "publishedAt", "lockedAt", "lockReason", "createdAt", "updatedAt", "rowVersion", "etag", "byteSize", "sha256", "releases" ], "additionalProperties": false }, "StaffFileVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "versionNo": { "type": "integer", "minimum": 1 }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "originalFilename": { "type": "string", "minLength": 1, "maxLength": 255 }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 120 }, "stage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "publicNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "reviewState": { "type": "string", "enum": [ "draft", "ready", "rejected" ] }, "validatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "lockedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "lockReason": { "anyOf": [ { "type": "string", "enum": [ "publication", "baseline", "association" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "byteSize": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "releases": { "type": "array", "items": { "$ref": "#/components/schemas/StaffVersionRelease" } }, "companyAttribution": { "$ref": "#/components/schemas/PublicCompanyAttribution" }, "dmeContext": { "$ref": "#/components/schemas/PublicDmeContext" }, "baselineOriginalVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "requiredA2lVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "contributionReview": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "contributionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "state": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "itemId", "contributionId", "state" ], "additionalProperties": false }, "previousVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "internalNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "validationNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "createdBy": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "validatedBy": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/VersionRelation" } } }, "required": [ "id", "fileId", "versionNo", "versionLabel", "originalFilename", "mimeType", "stage", "publicNotes", "readType", "readMethod", "readTool", "fuelRequirement", "hardwareRequirements", "reviewState", "validatedAt", "publishedAt", "lockedAt", "lockReason", "createdAt", "updatedAt", "rowVersion", "etag", "byteSize", "sha256", "releases", "baselineOriginalVersionId", "previousVersionId", "internalNotes", "validationNotes", "createdBy", "validatedBy" ], "additionalProperties": false }, "PublicExtractedIdentifier": { "type": "object", "properties": { "namespace": { "type": "string", "minLength": 1, "maxLength": 100 }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 200 }, "source": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "originalField": { "type": "string", "minLength": 1, "maxLength": 200 }, "declared": { "type": "boolean" }, "status": { "type": "string", "enum": [ "identified", "candidate" ] }, "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "string", "minLength": 1, "maxLength": 80 } ] }, "interpretation": { "type": "object", "properties": { "classification": { "type": "string", "minLength": 1, "maxLength": 40 }, "explanation": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "classification", "explanation" ], "additionalProperties": false } }, "required": [ "namespace", "label", "value", "source" ], "additionalProperties": false }, "PublicIdentityMetadata": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "manufacturer", "ecu_manufacturer", "ecu_family", "ecu_variant", "engine_code", "engine_description", "platform_code", "vehicle_make", "vehicle_model", "model_year", "transmission", "drivetrain", "market" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "identified", "candidate" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ] } }, "required": [ "field", "label", "value", "status" ], "additionalProperties": false }, "CatalogueIdentity": { "type": "object", "properties": { "identityEnrichment": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "queued", "running", "retry_wait", "complete", "partial", "cancelled" ] }, "message": { "type": "string", "maxLength": 200 }, "updatedAt": { "type": "string", "format": "date-time" }, "identifiedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 }, "unresolvedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 } }, "required": [ "state", "message", "updatedAt", "identifiedFields", "unresolvedFields" ], "additionalProperties": false }, { "type": "null" } ] }, "declaredVehicle": { "anyOf": [ { "type": "object", "properties": { "make": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "make", "model" ], "additionalProperties": false }, { "type": "null" } ] }, "make": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "ecuFamily": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "ecuFamilySource": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/PublicExtractedIdentifier" }, "maxItems": 256 }, "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIdentityMetadata" }, "maxItems": 128 }, "canonicalSlug": { "type": "string", "minLength": 1, "maxLength": 8192 }, "vehicleIdentityStatus": { "type": "string", "enum": [ "verified_fitment", "web_matched", "ai_identified", "declared", "unavailable" ] }, "vehicleIdentitySource": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "make", "model", "ecuFamily", "ecuFamilySource", "identifiers", "metadata", "canonicalSlug", "vehicleIdentityStatus", "vehicleIdentitySource" ], "additionalProperties": false }, "PublicTuningObservation": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "aggressive_calibration", "diagnostic_changes", "protection_changes", "limiter_changes", "other" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "detail": { "type": "string", "minLength": 1, "maxLength": 600 } }, "required": [ "category", "title", "detail" ], "additionalProperties": false }, "File": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "kind": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "tuningStage": { "anyOf": [ { "type": "string", "enum": [ "stage1", "stage2", "custom_stage3", "unlocked" ] }, { "type": "null" } ], "description": "Uploader-defined modified file type. Unlocked uses stock-only comparison; it cannot be changed to or from a calibration type after upload. The label is not verification evidence or a performance claim." }, "publicationState": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "catalogueVisibility": { "type": "string", "enum": [ "public", "staff_only" ] }, "accessPolicy": { "type": "string", "enum": [ "members", "manual_grant", "paid_coming_soon", "staff_only", "credits" ] }, "publishedVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "plannedPriceMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "CAD" ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "version": { "anyOf": [ { "$ref": "#/components/schemas/FileVersion" }, { "type": "null" } ] }, "catalogueIdentity": { "$ref": "#/components/schemas/CatalogueIdentity" }, "tuningObservations": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTuningObservation" }, "maxItems": 8 }, "access": { "$ref": "#/components/schemas/AccessDecision" }, "creditPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "example": "30" }, { "type": "null" } ] }, "hasExactVersionEntitlement": { "type": "boolean" } }, "required": [ "id", "kind", "title", "description", "publicationState", "catalogueVisibility", "accessPolicy", "publishedVersionId", "plannedPriceMinor", "currency", "publishedAt", "archivedAt", "createdAt", "updatedAt", "rowVersion", "etag", "version", "access" ], "additionalProperties": false }, "StaffFile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "kind": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "tuningStage": { "anyOf": [ { "type": "string", "enum": [ "stage1", "stage2", "custom_stage3", "unlocked" ] }, { "type": "null" } ], "description": "Uploader-defined modified file type. Unlocked uses stock-only comparison; it cannot be changed to or from a calibration type after upload. The label is not verification evidence or a performance claim." }, "publicationState": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "catalogueVisibility": { "type": "string", "enum": [ "public", "staff_only" ] }, "accessPolicy": { "type": "string", "enum": [ "members", "manual_grant", "paid_coming_soon", "staff_only", "credits" ] }, "publishedVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "plannedPriceMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "CAD" ] }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "version": { "anyOf": [ { "$ref": "#/components/schemas/StaffFileVersion" }, { "type": "null" } ] }, "catalogueIdentity": { "$ref": "#/components/schemas/CatalogueIdentity" }, "tuningObservations": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTuningObservation" }, "maxItems": 8 }, "access": { "$ref": "#/components/schemas/AccessDecision" }, "createdBy": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "updatedBy": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "publishedBy": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "internalNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "creditPrice": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "example": "30" }, { "type": "null" } ] }, "creditPriceOverride": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "example": "30" }, { "type": "null" } ] }, "hasExactVersionEntitlement": { "type": "boolean" } }, "required": [ "id", "kind", "title", "description", "publicationState", "catalogueVisibility", "accessPolicy", "publishedVersionId", "plannedPriceMinor", "currency", "publishedAt", "archivedAt", "createdAt", "updatedAt", "rowVersion", "etag", "version", "access", "createdBy", "updatedBy", "publishedBy", "internalNotes" ], "additionalProperties": false }, "SoftwareReleaseDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "ecuTypeId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 180 }, "identificationStatus": { "type": "string", "enum": [ "unverified", "verified" ] }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, "rowVersion": { "type": "integer", "minimum": 1 }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "ecu": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "family": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "manufacturer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "id", "name", "family", "manufacturer" ], "additionalProperties": false }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Identifier" } }, "fitments": { "type": "array", "items": { "$ref": "#/components/schemas/Fitment" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "filesPage": { "$ref": "#/components/schemas/Page" } }, "required": [ "id", "ecuTypeId", "displayName", "identificationStatus", "verifiedAt", "createdAt", "updatedAt", "rowVersion", "etag", "ecu", "identifiers", "fitments", "files", "filesPage" ], "additionalProperties": false }, "RelatedFile": { "type": "object", "properties": { "relationType": { "type": "string", "enum": [ "baseline", "previous_revision", "definition_for", "documentation_for" ] }, "status": { "type": "string", "enum": [ "candidate", "verified" ] }, "file": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "kind": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] } }, "required": [ "id", "title", "kind" ], "additionalProperties": false }, "versionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "isCurrentPublished": { "type": "boolean" }, "dmeContext": { "$ref": "#/components/schemas/PublicDmeContext" } }, "required": [ "relationType", "status", "file", "versionId", "versionLabel", "isCurrentPublished" ], "additionalProperties": false }, "Facets": { "type": "object", "properties": { "kind": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "stage": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "accessPolicy": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "ecuManufacturerId": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "ecuTypeId": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "makeId": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "modelId": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "vehicleVariantId": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "year": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "make": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "model": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "ecu": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "ecuMaker": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "engine": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "platform": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } }, "modelYear": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "count": { "type": "integer", "minimum": 0 } }, "required": [ "value", "label", "count" ], "additionalProperties": false } } }, "required": [ "kind", "stage", "accessPolicy", "ecuManufacturerId", "ecuTypeId", "makeId", "modelId", "vehicleVariantId", "year", "make", "model", "ecu", "ecuMaker", "engine", "platform", "modelYear" ], "additionalProperties": false }, "UploadMetadata": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "catalogueVisibility": { "type": "string", "const": "staff_only" }, "accessPolicy": { "type": "string", "const": "staff_only" }, "plannedPriceMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "CAD" ] }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "stage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "publicNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "internalNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "baselineOriginalVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "previousVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "acknowledgeDuplicate": { "type": "boolean", "default": false }, "requiredA2lVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "releaseLinks": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseLinkInput" }, "maxItems": 100 }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/RelationInput" }, "maxItems": 100 } }, "required": [ "kind", "title", "versionLabel" ], "additionalProperties": false }, "VersionUploadMetadata": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "original_bin", "tuned_bin", "a2l", "document" ] }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "stage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "publicNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "internalNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "baselineOriginalVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "previousVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "acknowledgeDuplicate": { "type": "boolean", "default": false }, "requiredA2lVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "releaseLinks": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseLinkInput" }, "maxItems": 100 }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/RelationInput" }, "maxItems": 100 } }, "required": [ "versionLabel" ], "additionalProperties": false }, "VersionPatch": { "type": "object", "properties": { "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "stage": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "publicNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "internalNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "baselineOriginalVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "previousVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] }, "requiredA2lVersionId": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "FilePatch": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "internalNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] }, "catalogueVisibility": { "type": "string", "enum": [ "public", "staff_only" ] }, "accessPolicy": { "type": "string", "enum": [ "members", "manual_grant", "paid_coming_soon", "staff_only", "credits" ] }, "creditPriceOverride": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "example": "30" }, { "type": "null" } ] }, "plannedPriceMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "CAD" ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "VersionReleasesReplacement": { "type": "object", "properties": { "releaseLinks": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseLinkInput" }, "maxItems": 100 } }, "required": [ "releaseLinks" ], "additionalProperties": false }, "VersionRelationsReplacement": { "type": "object", "properties": { "relations": { "type": "array", "items": { "$ref": "#/components/schemas/RelationInput" }, "maxItems": 100 } }, "required": [ "relations" ], "additionalProperties": false }, "ReviewRequest": { "type": "object", "properties": { "reviewState": { "type": "string", "enum": [ "draft", "ready", "rejected" ] }, "validationNotes": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "reviewState" ], "additionalProperties": false }, "PublishRequest": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "catalogueVisibility": { "type": "string", "enum": [ "public", "staff_only" ] }, "accessPolicy": { "type": "string", "enum": [ "members", "manual_grant", "paid_coming_soon", "staff_only", "credits" ] }, "plannedPriceMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, { "type": "null" } ] }, "currency": { "type": "string", "enum": [ "CAD" ] } }, "required": [ "versionId", "catalogueVisibility", "accessPolicy" ], "additionalProperties": false }, "ArchiveRequest": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "UploadResult": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "versionId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "publicationState": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "reviewState": { "type": "string", "enum": [ "draft", "ready", "rejected" ] }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "byteSize": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,19})$", "description": "Unsigned integer as a decimal string; never coerce unsafely to a JavaScript number.", "example": "8388608" }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$", "example": "\"1\"" }, "file": { "$ref": "#/components/schemas/StaffFile" }, "version": { "$ref": "#/components/schemas/StaffFileVersion" }, "duplicateContent": { "type": "boolean" } }, "required": [ "fileId", "versionId", "publicationState", "reviewState", "sha256", "byteSize", "etag", "file", "version", "duplicateContent" ], "additionalProperties": false }, "RegistrationRequest": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "maxLength": 254, "format": "email" }, "password": { "type": "string", "minLength": 15, "maxLength": 128, "writeOnly": true, "example": "synthetic example passphrase" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "companyName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "returnTo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8000 }, { "type": "null" } ] }, "turnstileToken": { "type": "string", "minLength": 1, "maxLength": 2048, "writeOnly": true, "description": "Fresh single-use Turnstile token for action register. It is validated server-side and never logged or returned.", "example": "synthetic-turnstile-token" } }, "required": [ "email", "password", "displayName", "turnstileToken" ], "additionalProperties": false }, "LoginRequest": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "maxLength": 254, "format": "email" }, "password": { "type": "string", "maxLength": 128, "writeOnly": true, "example": "synthetic example passphrase" }, "turnstileToken": { "type": "string", "minLength": 1, "maxLength": 2048, "writeOnly": true, "description": "Fresh single-use Turnstile token for action login. A failed sign-in consumes the challenge.", "example": "synthetic-turnstile-token" } }, "required": [ "email", "password", "turnstileToken" ], "additionalProperties": false }, "EmailRequest": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "maxLength": 254, "format": "email" }, "returnTo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 8000 }, { "type": "null" } ] } }, "required": [ "email" ], "additionalProperties": false }, "VerifyEmailRequest": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true } }, "required": [ "token" ], "additionalProperties": false }, "ResetPasswordRequest": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "writeOnly": true }, "newPassword": { "type": "string", "minLength": 15, "maxLength": 128, "writeOnly": true, "example": "synthetic example passphrase" } }, "required": [ "token", "newPassword" ], "additionalProperties": false }, "ChangePasswordRequest": { "type": "object", "properties": { "currentPassword": { "type": "string", "maxLength": 128, "writeOnly": true, "example": "synthetic example passphrase" }, "newPassword": { "type": "string", "minLength": 15, "maxLength": 128, "writeOnly": true, "example": "synthetic example passphrase" } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false }, "ProfilePatch": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "companyName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "evcLicense": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4096 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "UserAccessPatch": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "customer", "editor", "admin" ] }, "status": { "type": "string", "enum": [ "pending_verification", "active", "suspended" ] }, "evcLicense": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 4096 }, { "type": "null" } ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "GrantCreate": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] } }, "required": [ "fileId", "reason" ], "additionalProperties": false }, "GrantPatch": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "update", "revoke", "reactivate" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "example": "2026-09-17T12:00:00.000Z" }, { "type": "null" } ] } }, "required": [ "action", "reason" ], "additionalProperties": false }, "RegisterResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } }, "required": [ "data" ], "additionalProperties": false }, "LoginResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthSession" } }, "required": [ "data" ], "additionalProperties": false }, "SessionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AuthSession" } }, "required": [ "data" ], "additionalProperties": false }, "VerifyEmailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VerificationResult" } }, "required": [ "data" ], "additionalProperties": false }, "ResendVerificationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } }, "required": [ "data" ], "additionalProperties": false }, "ForgotPasswordResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } }, "required": [ "data" ], "additionalProperties": false }, "PurchaseReconciliationListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaseReconciliationSummary" }, "maxItems": 20 }, "nextCursor": { "anyOf": [ { "type": "string", "format": "uuid", "example": "11111111-1111-4111-8111-111111111111" }, { "type": "null" } ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false }, "PurchaseReconciliationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PurchaseReconciliation" } }, "required": [ "data" ], "additionalProperties": false }, "ResolvePurchaseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PurchaseResolutionResult" } }, "required": [ "data" ], "additionalProperties": false }, "CheckoutPacksResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CheckoutPacks" } }, "required": [ "data" ], "additionalProperties": false }, "CreateCheckoutResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CheckoutOrder" } }, "required": [ "data" ], "additionalProperties": false }, "OwnPurchasesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PurchaserOrder" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "OwnPurchaseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CheckoutOrder" } }, "required": [ "data" ], "additionalProperties": false }, "ProfileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ], "additionalProperties": false }, "OwnCompanyVerificationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PrivateCompanyVerification" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateProfileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ], "additionalProperties": false }, "SessionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionDevice" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "MyDownloadsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DownloadEvent" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "MyGrantsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OwnGrant" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "SiteResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Site" } }, "required": [ "data" ], "additionalProperties": false }, "ListPublicVehicleMakesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleMake" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "ListAdminVehicleMakesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleMake" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "CreateVehicleMakeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleMake" } }, "required": [ "data" ], "additionalProperties": false }, "GetVehicleMakeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleMake" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateVehicleMakeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleMake" } }, "required": [ "data" ], "additionalProperties": false }, "ListPublicVehicleModelsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleModel" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "ListAdminVehicleModelsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleModel" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "CreateVehicleModelResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleModel" } }, "required": [ "data" ], "additionalProperties": false }, "GetVehicleModelResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleModel" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateVehicleModelResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleModel" } }, "required": [ "data" ], "additionalProperties": false }, "ListPublicVehicleVariantsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleVariant" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "ListAdminVehicleVariantsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VehicleVariant" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "CreateVehicleVariantResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleVariant" } }, "required": [ "data" ], "additionalProperties": false }, "GetVehicleVariantResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleVariant" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateVehicleVariantResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/VehicleVariant" } }, "required": [ "data" ], "additionalProperties": false }, "ListPublicEcuManufacturersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EcuManufacturer" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "ListAdminEcuManufacturersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EcuManufacturer" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "CreateEcuManufacturerResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EcuManufacturer" } }, "required": [ "data" ], "additionalProperties": false }, "GetEcuManufacturerResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EcuManufacturer" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateEcuManufacturerResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EcuManufacturer" } }, "required": [ "data" ], "additionalProperties": false }, "ListPublicEcuTypesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EcuType" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "ListAdminEcuTypesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EcuType" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "CreateEcuTypeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EcuType" } }, "required": [ "data" ], "additionalProperties": false }, "GetEcuTypeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EcuType" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateEcuTypeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EcuType" } }, "required": [ "data" ], "additionalProperties": false }, "FilesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "FileFacetsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Facets" } }, "required": [ "data" ], "additionalProperties": false }, "FileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/File" } }, "required": [ "data" ], "additionalProperties": false }, "RelatedFilesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RelatedFile" } } }, "required": [ "data" ], "additionalProperties": false }, "SoftwareReleasesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SoftwareRelease" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "SoftwareReleaseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SoftwareReleaseDetail" } }, "required": [ "data" ], "additionalProperties": false }, "AdminSoftwareReleasesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffSoftwareRelease" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "CreateSoftwareReleaseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffSoftwareRelease" } }, "required": [ "data" ], "additionalProperties": false }, "AdminSoftwareReleaseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffSoftwareRelease" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateSoftwareReleaseResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffSoftwareRelease" } }, "required": [ "data" ], "additionalProperties": false }, "ReplaceIdentifiersResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffSoftwareRelease" } }, "required": [ "data" ], "additionalProperties": false }, "ReplaceFitmentsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffSoftwareRelease" } }, "required": [ "data" ], "additionalProperties": false }, "AdminFilesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffFile" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "UploadFileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UploadResult" } }, "required": [ "data" ], "additionalProperties": false }, "AdminFileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFile" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateFileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFile" } }, "required": [ "data" ], "additionalProperties": false }, "FileVersionsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StaffFileVersion" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "UploadVersionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UploadResult" } }, "required": [ "data" ], "additionalProperties": false }, "FileVersionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFileVersion" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateVersionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFileVersion" } }, "required": [ "data" ], "additionalProperties": false }, "ReplaceVersionReleasesResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFileVersion" } }, "required": [ "data" ], "additionalProperties": false }, "ReplaceVersionRelationsResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFileVersion" } }, "required": [ "data" ], "additionalProperties": false }, "ReviewVersionResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFileVersion" } }, "required": [ "data" ], "additionalProperties": false }, "PublishFileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFile" } }, "required": [ "data" ], "additionalProperties": false }, "ArchiveFileResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/StaffFile" } }, "required": [ "data" ], "additionalProperties": false }, "AdminUsersResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "AdminCompanyVerificationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminCompanyVerification" } }, "required": [ "data" ], "additionalProperties": false }, "ChangeCompanyVerificationResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminCompanyVerification" } }, "required": [ "data" ], "additionalProperties": false }, "AdminUserResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateUserAccessResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": [ "data" ], "additionalProperties": false }, "UserGrantsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GrantWithTitle" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "CreateGrantResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Grant" } }, "required": [ "data" ], "additionalProperties": false }, "GrantResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Grant" } }, "required": [ "data" ], "additionalProperties": false }, "UpdateGrantResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Grant" } }, "required": [ "data" ], "additionalProperties": false }, "AuditEventsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "page": { "$ref": "#/components/schemas/Page" } }, "required": [ "data", "page" ], "additionalProperties": false }, "UpdateSiteResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminSite" } }, "required": [ "data" ], "additionalProperties": false }, "AdminSiteResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdminSite" } }, "required": [ "data" ], "additionalProperties": false }, "CreditWallet": { "type": "object", "additionalProperties": false, "properties": { "balance": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "accountRestriction": { "type": "string", "enum": [ "none", "review_hold", "debt" ] }, "pendingRewardEstimate": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "examples": [ "0" ] }, "etag": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "balance", "accountRestriction", "pendingRewardEstimate" ] }, "CreditLedgerEntry": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "type": { "enum": [ "upload_reward", "download_debit", "reward_reversal", "download_refund", "admin_adjustment", "purchase_grant", "purchase_recovery", "purchase_restore" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "balanceAfter": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "createdAt": { "type": "string", "format": "date-time" }, "referenceType": { "type": "string", "minLength": 1, "maxLength": 80 }, "referenceId": { "type": "string", "format": "uuid" }, "reversalOfEntryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "id", "amount", "type", "reason", "balanceAfter", "createdAt", "referenceType", "referenceId", "reversalOfEntryId" ] }, "DownloadQuoteRequest": { "type": "object", "additionalProperties": false, "properties": { "versionId": { "type": "string", "format": "uuid" } }, "required": [ "versionId" ] }, "DownloadQuote": { "type": "object", "additionalProperties": false, "properties": { "quoteId": { "type": "string", "format": "uuid" }, "fileId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "examples": [ "0" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "alreadyEntitled": { "type": "boolean" }, "balance": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "policyId": { "type": "string", "format": "uuid" } }, "required": [ "quoteId", "fileId", "versionId", "price", "expiresAt", "alreadyEntitled", "balance", "policyId" ] }, "DownloadAcquisitionRequest": { "type": "object", "additionalProperties": false, "properties": { "quoteId": { "type": "string", "format": "uuid" } }, "required": [ "quoteId" ] }, "DownloadAcquisition": { "type": "object", "additionalProperties": false, "properties": { "acquisitionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "fileId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "charge": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "examples": [ "0" ] }, "balance": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "alreadyEntitled": { "type": "boolean" }, "downloadUrl": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "acquisitionId", "fileId", "versionId", "charge", "balance", "alreadyEntitled", "downloadUrl" ] }, "AcquiredVersion": { "type": "object", "additionalProperties": false, "properties": { "entitlementId": { "type": "string", "format": "uuid" }, "acquisitionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "source": { "enum": [ "credits", "contributor", "admin" ] }, "fileId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "examples": [ "0" ] }, "acquiredAt": { "type": "string", "format": "date-time" }, "available": { "type": "boolean" }, "unavailableReason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "downloadUrl": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 256 }, { "type": "null" } ] } }, "required": [ "entitlementId", "acquisitionId", "source", "fileId", "versionId", "title", "versionLabel", "price", "acquiredAt", "available", "unavailableReason", "downloadUrl" ] }, "CreateCreditPolicy": { "type": "object", "additionalProperties": false, "properties": { "stockReward": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "stockPrice": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "a2lReward": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "a2lPrice": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "tunedReward": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "tunedPrice": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "effectiveAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "stockReward", "stockPrice", "a2lReward", "a2lPrice", "tunedReward", "tunedPrice", "effectiveAt", "reason" ] }, "CreditPolicyRecord": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "stockReward": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "stockPrice": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "a2lReward": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "a2lPrice": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "tunedReward": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "tunedPrice": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "effectiveAt": { "type": "string", "format": "date-time" }, "activatedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "etag": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "id", "version", "stockReward", "stockPrice", "a2lReward", "a2lPrice", "tunedReward", "tunedPrice", "reason", "effectiveAt", "activatedAt", "isActive", "etag" ] }, "CreditReason": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ] }, "CreditAdjustmentRequest": { "type": "object", "additionalProperties": false, "properties": { "userId": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^-?[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "userId", "amount", "reason" ] }, "CreditMutation": { "type": "object", "additionalProperties": false, "properties": { "ledgerEntryId": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "balance": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "accountRestriction": { "type": "string", "enum": [ "none", "review_hold", "debt" ] }, "alreadyCompensated": { "type": "boolean" } }, "required": [ "ledgerEntryId", "amount", "balance", "accountRestriction" ] }, "WalletRestrictionRequest": { "type": "object", "additionalProperties": false, "properties": { "restriction": { "enum": [ "none", "review_hold" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "restriction", "reason" ] }, "WalletRestriction": { "type": "object", "additionalProperties": false, "properties": { "balance": { "type": "string", "pattern": "^(0|-?[1-9][0-9]{0,18})$", "examples": [ "30" ] }, "accountRestriction": { "type": "string", "enum": [ "none", "review_hold", "debt" ] }, "etag": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "balance", "accountRestriction", "etag" ] }, "ContributionDecisionRequest": { "type": "object", "additionalProperties": false, "properties": { "decision": { "enum": [ "accept", "reject", "needs_review" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceIds": { "type": "array", "maxItems": 128, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } }, "manualReview": { "type": "boolean" } }, "required": [ "decision", "reason", "evidenceIds" ] }, "ContributionDecision": { "type": "object", "additionalProperties": false, "properties": { "itemId": { "type": "string", "format": "uuid" }, "state": { "enum": [ "accepted", "duplicate", "rejected", "needs_review", "withdrawn" ] }, "reasonCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "rewardState": { "enum": [ "pending", "awarded", "not_eligible", "reversed" ] }, "rewardAmount": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, { "type": "null" } ] }, "canonicalContributionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "versionId": { "type": "string", "format": "uuid" }, "etag": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "itemId", "state", "reasonCode", "rewardState", "rewardAmount", "canonicalContributionId", "versionId", "etag" ] }, "StaffProvenanceRequest": { "type": "object", "additionalProperties": false, "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 1000 }, "basis": { "enum": [ "documented_original_read", "supplier_record" ] } }, "required": [ "summary", "sourceReference", "basis" ] }, "StaffProvenance": { "type": "object", "additionalProperties": false, "properties": { "evidenceId": { "type": "string", "format": "uuid" }, "verificationRunId": { "type": "string", "format": "uuid" }, "basis": { "enum": [ "documented_original_read", "supplier_record" ] } }, "required": [ "evidenceId", "verificationRunId", "basis" ] }, "DuplicateCandidate": { "type": "object", "additionalProperties": false, "properties": { "canonicalContributionId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "versionEtag": { "type": "string", "minLength": 1, "maxLength": 40 }, "fileId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "kind": { "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "reviewState": { "enum": [ "unreviewed", "accepted" ] }, "status": { "enum": [ "active", "withdrawn" ] }, "reason": { "enum": [ "EXACT_HASH", "SHARED_SOFTWARE_REVIEW_CANDIDATE" ] } }, "required": [ "canonicalContributionId", "versionId", "versionEtag", "fileId", "title", "sha256", "kind", "reviewState", "status", "reason" ] }, "StaffEquivalenceRequest": { "type": "object", "additionalProperties": false, "properties": { "canonicalContributionId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "sourceReference": { "type": "string", "minLength": 1, "maxLength": 1000 }, "evidenceIds": { "type": "array", "maxItems": 128, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } }, "required": [ "canonicalContributionId", "reason", "sourceReference", "evidenceIds" ] }, "StockAssociationRequest": { "type": "object", "additionalProperties": false, "properties": { "stockVersionId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceIds": { "type": "array", "maxItems": 128, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } }, "required": [ "stockVersionId", "reason", "evidenceIds" ] }, "StockAssociation": { "type": "object", "additionalProperties": false, "properties": { "relationId": { "type": "string", "format": "uuid" }, "sourceVersionId": { "type": "string", "format": "uuid" }, "stockVersionId": { "type": "string", "format": "uuid" }, "alreadyAssociated": { "type": "boolean" }, "reward": { "const": "0" } }, "required": [ "relationId", "sourceVersionId", "stockVersionId", "alreadyAssociated", "reward" ] }, "LegacyCreditReviewRequest": { "type": "object", "additionalProperties": false, "properties": { "verificationItemId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceIds": { "type": "array", "maxItems": 128, "uniqueItems": true, "items": { "type": "string", "format": "uuid" } } }, "required": [ "verificationItemId", "reason", "evidenceIds" ] }, "LegacyCreditReview": { "type": "object", "additionalProperties": false, "properties": { "versionId": { "type": "string", "format": "uuid" }, "canonicalContributionId": { "type": "string", "format": "uuid" }, "reviewState": { "const": "accepted" }, "creditEnrolled": { "const": false }, "retroactiveReward": { "const": "0" }, "etag": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "versionId", "canonicalContributionId", "reviewState", "creditEnrolled", "retroactiveReward", "etag" ] }, "AdminRewardClaim": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "canonicalContributionId": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] }, "ledgerEntryId": { "type": "string", "format": "uuid" }, "reversed": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "userId", "itemId", "versionId", "canonicalContributionId", "amount", "ledgerEntryId", "reversed", "createdAt" ] }, "AdminDownloadAcquisition": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "fileId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "price": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "examples": [ "0" ] }, "ledgerEntryId": { "type": "string", "format": "uuid" }, "refundLedgerEntryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refunded": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "userId", "fileId", "versionId", "price", "ledgerEntryId", "refundLedgerEntryId", "refunded", "createdAt" ] }, "VersionWithdrawal": { "type": "object", "additionalProperties": false, "properties": { "versionId": { "type": "string", "format": "uuid" }, "withdrawalState": { "const": "withdrawn" }, "affectedVersionIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "entitlementReview": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "entitlementId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "source": { "enum": [ "credits", "contributor", "admin" ] }, "acquisitionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "entitlementId", "userId", "versionId", "source", "acquisitionId" ] } }, "rewardReview": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "rewardClaimId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "examples": [ "30" ] } }, "required": [ "rewardClaimId", "userId", "versionId", "amount" ] } }, "automaticCompensation": { "const": false } }, "required": [ "versionId", "withdrawalState", "affectedVersionIds", "entitlementReview", "rewardReview", "automaticCompensation" ] }, "IdentityEnrichmentStatus": { "type": "object", "properties": { "state": { "enum": [ "queued", "running", "retry_wait", "complete", "partial", "cancelled" ] }, "message": { "type": "string", "maxLength": 200 }, "updatedAt": { "type": "string", "format": "date-time" }, "identifiedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 }, "unresolvedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 } }, "required": [ "state", "message", "updatedAt", "identifiedFields", "unresolvedFields" ], "additionalProperties": false }, "IdentityCheckpoint": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "field": { "enum": [ "manufacturer", "ecu_manufacturer", "ecu_family", "ecu_variant", "engine_code", "engine_description", "platform_code", "vehicle_make", "vehicle_model", "model_year", "transmission", "drivetrain", "market", "part_number", "hardware_identifier", "software_identifier", "software_version", "application_identifier", "calibration_identifier", "bootloader_identifier", "project_identifier", "other_identifier" ] }, "value": { "type": "string", "maxLength": 160, "minLength": 1 }, "status": { "enum": [ "identified", "candidate" ] }, "confidence": { "enum": [ "high", "medium", "low" ] }, "explanation": { "type": "string", "maxLength": 400 }, "source": { "enum": [ "binary", "web", "combined" ] }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] }, "evidenceKeys": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 16 } }, "required": [ "field", "value", "status", "confidence", "explanation", "source", "offset", "evidenceKeys" ], "additionalProperties": false }, "maxItems": 64 }, "observations": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "maxLength": 40 }, "input": { "type": "string", "maxLength": 1000 }, "output": { "type": "string", "maxLength": 6000 } }, "required": [ "tool", "input", "output" ], "additionalProperties": false }, "maxItems": 16 }, "webResults": { "type": "array", "items": { "type": "object", "properties": { "resultId": { "type": "string", "pattern": "^search-[1-9][0-9]?$" }, "url": { "type": "string", "maxLength": 2048 } }, "required": [ "resultId", "url" ], "additionalProperties": false }, "maxItems": 80 }, "limitations": { "type": "array", "items": { "type": "string", "maxLength": 180 }, "maxItems": 8 } }, "required": [ "findings", "observations", "webResults", "limitations" ], "additionalProperties": false }, "IdentitySave": { "type": "object", "properties": { "sequence": { "type": "integer", "minimum": 1, "maximum": 1000 }, "checkpoint": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "field": { "enum": [ "manufacturer", "ecu_manufacturer", "ecu_family", "ecu_variant", "engine_code", "engine_description", "platform_code", "vehicle_make", "vehicle_model", "model_year", "transmission", "drivetrain", "market", "part_number", "hardware_identifier", "software_identifier", "software_version", "application_identifier", "calibration_identifier", "bootloader_identifier", "project_identifier", "other_identifier" ] }, "value": { "type": "string", "maxLength": 160, "minLength": 1 }, "status": { "enum": [ "identified", "candidate" ] }, "confidence": { "enum": [ "high", "medium", "low" ] }, "explanation": { "type": "string", "maxLength": 400 }, "source": { "enum": [ "binary", "web", "combined" ] }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] }, "evidenceKeys": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 16 } }, "required": [ "field", "value", "status", "confidence", "explanation", "source", "offset", "evidenceKeys" ], "additionalProperties": false }, "maxItems": 64 }, "observations": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "maxLength": 40 }, "input": { "type": "string", "maxLength": 1000 }, "output": { "type": "string", "maxLength": 6000 } }, "required": [ "tool", "input", "output" ], "additionalProperties": false }, "maxItems": 16 }, "webResults": { "type": "array", "items": { "type": "object", "properties": { "resultId": { "type": "string", "pattern": "^search-[1-9][0-9]?$" }, "url": { "type": "string", "maxLength": 2048 } }, "required": [ "resultId", "url" ], "additionalProperties": false }, "maxItems": 80 }, "limitations": { "type": "array", "items": { "type": "string", "maxLength": 180 }, "maxItems": 8 } }, "required": [ "findings", "observations", "webResults", "limitations" ], "additionalProperties": false }, "outcome": { "enum": [ "checkpoint", "complete", "interrupted" ] }, "modelId": { "type": "string", "maxLength": 100, "minLength": 1 }, "usage": { "type": "object", "properties": { "modelRequests": { "type": "integer", "minimum": 0, "maximum": 64 }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 64 }, "searches": { "type": "integer", "minimum": 0, "maximum": 12 }, "inputTokens": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 65536 }, "costMicros": { "type": "integer", "minimum": 0, "maximum": 5000000 } }, "required": [ "modelRequests", "toolCalls", "searches", "inputTokens", "outputTokens", "costMicros" ], "additionalProperties": false } }, "required": [ "sequence", "checkpoint", "outcome", "modelId", "usage" ], "additionalProperties": false }, "IdentityWorkerLease": { "type": "object", "properties": { "contractVersion": { "const": "1" }, "jobId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "attemptNo": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "leaseGeneration": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "inputFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "allowedVersionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 16, "uniqueItems": true }, "item": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "itemId": { "type": "string", "format": "uuid" }, "contributionId": { "type": "string", "format": "uuid" }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "itemId", "contributionId", "claims" ], "additionalProperties": false }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "accepted": { "type": "boolean" }, "analysisAllowed": { "type": "boolean" }, "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "role", "submittedVersionId", "accepted", "stockVersionId" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "profile": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "adapterKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "dumpLayout": { "type": "string", "minLength": 1, "maxLength": 100 }, "capabilities": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 32 }, "enabled": { "type": "boolean" }, "autoAcceptEnabled": { "type": "boolean" } }, "required": [ "id", "profileKey", "profileVersion", "adapterKey", "kind", "dumpLayout", "capabilities", "enabled", "autoAcceptEnabled" ], "additionalProperties": false }, { "type": "null" } ] }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "aiResearchEnabled": { "type": "boolean" }, "checksumVerificationEnabled": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "limits": { "type": "object", "properties": { "researchTimeoutMs": { "const": 720000 }, "maxRunMs": { "const": 780000 }, "maxToolCalls": { "const": 64 }, "maxSearches": { "const": 12 }, "maxInputTokens": { "const": 1000000 }, "maxOutputTokens": { "const": 65536 }, "maxCostMicros": { "const": "5000000" }, "maxReadRangeBytes": { "const": 4096 }, "maxToolOutputBytes": { "const": 32768 }, "maxResultBytes": { "const": 262144 } }, "required": [ "researchTimeoutMs", "maxRunMs", "maxToolCalls", "maxSearches", "maxInputTokens", "maxOutputTokens", "maxCostMicros", "maxReadRangeBytes", "maxToolOutputBytes", "maxResultBytes" ], "additionalProperties": false }, "leaseToken": { "type": "string", "minLength": 32, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "leaseExpiresAt": { "type": "string", "format": "date-time" } }, "required": [ "contractVersion", "jobId", "runId", "attemptNo", "leaseGeneration", "inputFingerprint", "allowedVersionIds", "item", "dependencies", "profile", "policyVersion", "aiResearchEnabled", "checksumVerificationEnabled", "limits", "leaseToken", "leaseExpiresAt" ], "additionalProperties": false }, "IdentityClaim": { "type": "object", "properties": { "lease": { "type": "object", "properties": { "contractVersion": { "const": "1" }, "jobId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "attemptNo": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "leaseGeneration": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "inputFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "allowedVersionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 16, "uniqueItems": true }, "item": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "itemId": { "type": "string", "format": "uuid" }, "contributionId": { "type": "string", "format": "uuid" }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "itemId", "contributionId", "claims" ], "additionalProperties": false }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "accepted": { "type": "boolean" }, "analysisAllowed": { "type": "boolean" }, "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "role", "submittedVersionId", "accepted", "stockVersionId" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "profile": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "adapterKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "dumpLayout": { "type": "string", "minLength": 1, "maxLength": 100 }, "capabilities": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 32 }, "enabled": { "type": "boolean" }, "autoAcceptEnabled": { "type": "boolean" } }, "required": [ "id", "profileKey", "profileVersion", "adapterKey", "kind", "dumpLayout", "capabilities", "enabled", "autoAcceptEnabled" ], "additionalProperties": false }, { "type": "null" } ] }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "aiResearchEnabled": { "type": "boolean" }, "checksumVerificationEnabled": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "limits": { "type": "object", "properties": { "researchTimeoutMs": { "const": 720000 }, "maxRunMs": { "const": 780000 }, "maxToolCalls": { "const": 64 }, "maxSearches": { "const": 12 }, "maxInputTokens": { "const": 1000000 }, "maxOutputTokens": { "const": 65536 }, "maxCostMicros": { "const": "5000000" }, "maxReadRangeBytes": { "const": 4096 }, "maxToolOutputBytes": { "const": 32768 }, "maxResultBytes": { "const": 262144 } }, "required": [ "researchTimeoutMs", "maxRunMs", "maxToolCalls", "maxSearches", "maxInputTokens", "maxOutputTokens", "maxCostMicros", "maxReadRangeBytes", "maxToolOutputBytes", "maxResultBytes" ], "additionalProperties": false }, "leaseToken": { "type": "string", "minLength": 32, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "leaseExpiresAt": { "type": "string", "format": "date-time" } }, "required": [ "contractVersion", "jobId", "runId", "attemptNo", "leaseGeneration", "inputFingerprint", "allowedVersionIds", "item", "dependencies", "profile", "policyVersion", "aiResearchEnabled", "checksumVerificationEnabled", "limits", "leaseToken", "leaseExpiresAt" ], "additionalProperties": false }, "checkpoint": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "field": { "enum": [ "manufacturer", "ecu_manufacturer", "ecu_family", "ecu_variant", "engine_code", "engine_description", "platform_code", "vehicle_make", "vehicle_model", "model_year", "transmission", "drivetrain", "market", "part_number", "hardware_identifier", "software_identifier", "software_version", "application_identifier", "calibration_identifier", "bootloader_identifier", "project_identifier", "other_identifier" ] }, "value": { "type": "string", "maxLength": 160, "minLength": 1 }, "status": { "enum": [ "identified", "candidate" ] }, "confidence": { "enum": [ "high", "medium", "low" ] }, "explanation": { "type": "string", "maxLength": 400 }, "source": { "enum": [ "binary", "web", "combined" ] }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] }, "evidenceKeys": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 16 } }, "required": [ "field", "value", "status", "confidence", "explanation", "source", "offset", "evidenceKeys" ], "additionalProperties": false }, "maxItems": 64 }, "observations": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "maxLength": 40 }, "input": { "type": "string", "maxLength": 1000 }, "output": { "type": "string", "maxLength": 6000 } }, "required": [ "tool", "input", "output" ], "additionalProperties": false }, "maxItems": 16 }, "webResults": { "type": "array", "items": { "type": "object", "properties": { "resultId": { "type": "string", "pattern": "^search-[1-9][0-9]?$" }, "url": { "type": "string", "maxLength": 2048 } }, "required": [ "resultId", "url" ], "additionalProperties": false }, "maxItems": 80 }, "limitations": { "type": "array", "items": { "type": "string", "maxLength": 180 }, "maxItems": 8 } }, "required": [ "findings", "observations", "webResults", "limitations" ], "additionalProperties": false }, "relatedContext": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "field": { "enum": [ "manufacturer", "ecu_manufacturer", "ecu_family", "ecu_variant", "engine_code", "engine_description", "platform_code", "vehicle_make", "vehicle_model", "model_year", "transmission", "drivetrain", "market", "part_number", "hardware_identifier", "software_identifier", "software_version", "application_identifier", "calibration_identifier", "bootloader_identifier", "project_identifier", "other_identifier" ] }, "value": { "type": "string", "maxLength": 160, "minLength": 1 }, "status": { "enum": [ "identified", "candidate" ] }, "confidence": { "enum": [ "high", "medium", "low" ] }, "explanation": { "type": "string", "maxLength": 400 }, "source": { "enum": [ "binary", "web", "combined" ] }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] }, "evidenceKeys": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 16 } }, "required": [ "field", "value", "status", "confidence", "explanation", "source", "offset", "evidenceKeys" ], "additionalProperties": false }, "maxItems": 64 }, "observations": { "type": "array", "items": { "type": "object", "properties": { "tool": { "type": "string", "maxLength": 40 }, "input": { "type": "string", "maxLength": 1000 }, "output": { "type": "string", "maxLength": 6000 } }, "required": [ "tool", "input", "output" ], "additionalProperties": false }, "maxItems": 16 } }, "required": [ "versionId", "kind", "sha256", "findings", "observations" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 } }, "required": [ "lease", "checkpoint", "relatedContext" ], "additionalProperties": false }, "ContributionClaims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "CreateContribution": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "SubmitContribution": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "ReplaceItemMetadata": { "type": "object", "properties": { "permissionConfirmed": { "const": true }, "permissionTextVersion": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "permissionConfirmed", "permissionTextVersion" ], "additionalProperties": false }, "CancelContribution": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [], "additionalProperties": false }, "RetryItem": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "UploadItemMetadata": { "type": "object", "properties": { "clientItemId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "type": "string", "minLength": 0, "maxLength": 4000 }, "tuningStage": { "anyOf": [ { "type": "string", "enum": [ "stage1", "stage2", "custom_stage3", "unlocked" ] }, { "type": "null" } ] }, "dmeContext": { "type": "object", "properties": { "clientSetId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "clientSetId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "clientItemId", "kind", "claims" ], "additionalProperties": false }, "EditItem": { "type": "object", "properties": { "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "dmeContext": { "anyOf": [ { "type": "object", "properties": { "clientSetId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "clientSetId", "dmeRole", "fileRole" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "claims" ], "additionalProperties": false }, "EditItemMetadata": { "type": "object", "properties": { "description": { "type": "string", "minLength": 0, "maxLength": 4000 }, "tuningStage": { "anyOf": [ { "type": "string", "enum": [ "stage1", "stage2", "custom_stage3", "unlocked" ] }, { "type": "null" } ] } }, "required": [ "description", "tuningStage" ], "additionalProperties": false }, "SetDependencies": { "type": "object", "properties": { "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "a2lVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [], "additionalProperties": false }, "StockRelationshipProof": { "type": "object", "properties": { "proofVersion": { "const": "1" }, "inputFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "interpretation": { "type": "string", "enum": [ "selected_submitted", "retained_canonical_resolved" ] }, "recordedStockVersionId": { "type": "string", "format": "uuid" }, "stockSubmittedVersionId": { "type": "string", "format": "uuid" }, "stockResolvedVersionId": { "type": "string", "format": "uuid" }, "a2lSubmittedVersionId": { "type": "string", "format": "uuid" }, "a2lResolvedVersionId": { "type": "string", "format": "uuid" } }, "required": [ "proofVersion", "inputFingerprint", "interpretation", "recordedStockVersionId", "stockSubmittedVersionId", "stockResolvedVersionId", "a2lSubmittedVersionId", "a2lResolvedVersionId" ], "additionalProperties": false }, "WorkerInput": { "type": "object", "properties": { "contractVersion": { "const": "1" }, "bundleContextVersion": { "const": "2" }, "jobId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "attemptNo": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "leaseGeneration": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "inputFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "allowedVersionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 16, "uniqueItems": true }, "item": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "itemId": { "type": "string", "format": "uuid" }, "contributionId": { "type": "string", "format": "uuid" }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "itemId", "contributionId", "claims" ], "additionalProperties": false }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "accepted": { "type": "boolean" }, "analysisAllowed": { "type": "boolean" }, "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "role", "submittedVersionId", "accepted", "stockVersionId" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "stockRelationshipProof": { "type": "object", "properties": { "proofVersion": { "const": "1" }, "inputFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "interpretation": { "type": "string", "enum": [ "selected_submitted", "retained_canonical_resolved" ] }, "recordedStockVersionId": { "type": "string", "format": "uuid" }, "stockSubmittedVersionId": { "type": "string", "format": "uuid" }, "stockResolvedVersionId": { "type": "string", "format": "uuid" }, "a2lSubmittedVersionId": { "type": "string", "format": "uuid" }, "a2lResolvedVersionId": { "type": "string", "format": "uuid" } }, "required": [ "proofVersion", "inputFingerprint", "interpretation", "recordedStockVersionId", "stockSubmittedVersionId", "stockResolvedVersionId", "a2lSubmittedVersionId", "a2lResolvedVersionId" ], "additionalProperties": false }, "companionTune": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "const": "tuned_bin" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "stockVersionId": { "type": "string", "format": "uuid" }, "a2lVersionId": { "type": "string", "format": "uuid" }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "stockVersionId", "a2lVersionId" ], "additionalProperties": false }, "companionTunes": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "const": "tuned_bin" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "stockVersionId": { "type": "string", "format": "uuid" }, "a2lVersionId": { "type": "string", "format": "uuid" }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "stockVersionId", "a2lVersionId", "dmeContext" ], "additionalProperties": false }, "minItems": 1, "maxItems": 2 }, "profile": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "adapterKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "dumpLayout": { "type": "string", "minLength": 1, "maxLength": 100 }, "capabilities": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 32 }, "enabled": { "type": "boolean" }, "autoAcceptEnabled": { "type": "boolean" } }, "required": [ "id", "profileKey", "profileVersion", "adapterKey", "kind", "dumpLayout", "capabilities", "enabled", "autoAcceptEnabled" ], "additionalProperties": false }, { "type": "null" } ] }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "aiResearchEnabled": { "type": "boolean" }, "checksumVerificationEnabled": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "limits": { "type": "object", "properties": { "researchTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 720000 }, "maxRunMs": { "type": "integer", "minimum": 1000, "maximum": 900000 }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 100 }, "maxSearches": { "type": "integer", "minimum": 0, "maximum": 20 }, "maxInputTokens": { "type": "integer", "minimum": 256, "maximum": 1000000 }, "maxOutputTokens": { "type": "integer", "minimum": 256, "maximum": 65536 }, "maxCostMicros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})$", "description": "Decimal micro-units, at most 100000000." }, "maxReadRangeBytes": { "type": "integer", "minimum": 1, "maximum": 65536 }, "maxToolOutputBytes": { "type": "integer", "minimum": 1024, "maximum": 131072 }, "maxResultBytes": { "type": "integer", "minimum": 16384, "maximum": 1048576 } }, "required": [ "researchTimeoutMs", "maxRunMs", "maxToolCalls", "maxSearches", "maxInputTokens", "maxOutputTokens", "maxCostMicros", "maxReadRangeBytes", "maxToolOutputBytes", "maxResultBytes" ], "additionalProperties": false } }, "required": [ "contractVersion", "jobId", "runId", "attemptNo", "leaseGeneration", "inputFingerprint", "allowedVersionIds", "item", "dependencies", "profile", "policyVersion", "aiResearchEnabled", "limits" ], "additionalProperties": false }, "WorkerLease": { "type": "object", "properties": { "contractVersion": { "const": "1" }, "bundleContextVersion": { "const": "2" }, "jobId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "attemptNo": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "leaseGeneration": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "inputFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "allowedVersionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 16, "uniqueItems": true }, "item": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "itemId": { "type": "string", "format": "uuid" }, "contributionId": { "type": "string", "format": "uuid" }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "itemId", "contributionId", "claims" ], "additionalProperties": false }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "accepted": { "type": "boolean" }, "analysisAllowed": { "type": "boolean" }, "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "role", "submittedVersionId", "accepted", "stockVersionId" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "stockRelationshipProof": { "type": "object", "properties": { "proofVersion": { "const": "1" }, "inputFingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "interpretation": { "type": "string", "enum": [ "selected_submitted", "retained_canonical_resolved" ] }, "recordedStockVersionId": { "type": "string", "format": "uuid" }, "stockSubmittedVersionId": { "type": "string", "format": "uuid" }, "stockResolvedVersionId": { "type": "string", "format": "uuid" }, "a2lSubmittedVersionId": { "type": "string", "format": "uuid" }, "a2lResolvedVersionId": { "type": "string", "format": "uuid" } }, "required": [ "proofVersion", "inputFingerprint", "interpretation", "recordedStockVersionId", "stockSubmittedVersionId", "stockResolvedVersionId", "a2lSubmittedVersionId", "a2lResolvedVersionId" ], "additionalProperties": false }, "companionTune": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "const": "tuned_bin" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "stockVersionId": { "type": "string", "format": "uuid" }, "a2lVersionId": { "type": "string", "format": "uuid" }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "stockVersionId", "a2lVersionId" ], "additionalProperties": false }, "companionTunes": { "type": "array", "items": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "const": "tuned_bin" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "stockVersionId": { "type": "string", "format": "uuid" }, "a2lVersionId": { "type": "string", "format": "uuid" }, "dmeContext": { "type": "object", "properties": { "contextVersion": { "const": "1" }, "setId": { "type": "string", "format": "uuid" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "contextVersion", "setId", "dmeRole", "fileRole" ], "additionalProperties": false } }, "required": [ "versionId", "kind", "sha256", "byteSize", "stockVersionId", "a2lVersionId", "dmeContext" ], "additionalProperties": false }, "minItems": 1, "maxItems": 2 }, "profile": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "adapterKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "dumpLayout": { "type": "string", "minLength": 1, "maxLength": 100 }, "capabilities": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 0, "maxItems": 32 }, "enabled": { "type": "boolean" }, "autoAcceptEnabled": { "type": "boolean" } }, "required": [ "id", "profileKey", "profileVersion", "adapterKey", "kind", "dumpLayout", "capabilities", "enabled", "autoAcceptEnabled" ], "additionalProperties": false }, { "type": "null" } ] }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "aiResearchEnabled": { "type": "boolean" }, "checksumVerificationEnabled": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "limits": { "type": "object", "properties": { "researchTimeoutMs": { "type": "integer", "minimum": 1000, "maximum": 720000 }, "maxRunMs": { "type": "integer", "minimum": 1000, "maximum": 900000 }, "maxToolCalls": { "type": "integer", "minimum": 1, "maximum": 100 }, "maxSearches": { "type": "integer", "minimum": 0, "maximum": 20 }, "maxInputTokens": { "type": "integer", "minimum": 256, "maximum": 1000000 }, "maxOutputTokens": { "type": "integer", "minimum": 256, "maximum": 65536 }, "maxCostMicros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})$", "description": "Decimal micro-units, at most 100000000." }, "maxReadRangeBytes": { "type": "integer", "minimum": 1, "maximum": 65536 }, "maxToolOutputBytes": { "type": "integer", "minimum": 1024, "maximum": 131072 }, "maxResultBytes": { "type": "integer", "minimum": 16384, "maximum": 1048576 } }, "required": [ "researchTimeoutMs", "maxRunMs", "maxToolCalls", "maxSearches", "maxInputTokens", "maxOutputTokens", "maxCostMicros", "maxReadRangeBytes", "maxToolOutputBytes", "maxResultBytes" ], "additionalProperties": false }, "leaseToken": { "type": "string", "minLength": 32, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "leaseExpiresAt": { "type": "string", "format": "date-time" } }, "required": [ "contractVersion", "jobId", "runId", "attemptNo", "leaseGeneration", "inputFingerprint", "allowedVersionIds", "item", "dependencies", "profile", "policyVersion", "aiResearchEnabled", "limits", "leaseToken", "leaseExpiresAt" ], "additionalProperties": false }, "LeaseRequest": { "type": "object", "properties": { "workerId": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" } }, "required": [ "workerId" ], "additionalProperties": false }, "HeartbeatRequest": { "type": "object", "properties": { "leaseToken": { "type": "string", "minLength": 32, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "leaseGeneration": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "stage": { "type": "string", "enum": [ "queued", "inspect", "extract_identifiers", "integrity", "relationship", "evidence", "uniqueness", "finalize" ] }, "progress": { "type": "object", "properties": { "reviewed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "total": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, "required": [ "reviewed", "total" ], "additionalProperties": false } }, "required": [ "leaseToken", "leaseGeneration", "stage" ], "additionalProperties": false }, "WorkerResult": { "type": "object", "properties": { "tuningObservations": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "aggressive_calibration", "diagnostic_changes", "protection_changes", "limiter_changes", "other" ] }, "title": { "type": "string", "minLength": 8, "maxLength": 100 }, "detail": { "type": "string", "minLength": 20, "maxLength": 600 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 8 } }, "required": [ "category", "title", "detail", "evidenceKeys" ], "additionalProperties": false }, "minItems": 0, "maxItems": 8 }, "aiReview": { "type": "object", "properties": { "version": { "const": "tuning-ai-review.v1" }, "subjectVersionId": { "type": "string", "format": "uuid" }, "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "a2lVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "decision": { "type": "string", "enum": [ "approve", "review", "reject" ] }, "justification": { "type": "string", "minLength": 1, "maxLength": 1200 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 180 }, "minItems": 0, "maxItems": 8 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 1, "maxItems": 32, "uniqueItems": true }, "semanticMaps": { "anyOf": [ { "type": "object", "properties": { "declared": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "reviewed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "complete": { "type": "boolean" }, "supported": { "type": "integer", "minimum": 0, "maximum": 32768 }, "contradicted": { "type": "integer", "minimum": 0, "maximum": 32768 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "assessed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "supportedPercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "declared", "reviewed", "complete", "supported", "contradicted", "skipped", "assessed", "supportedPercent" ], "additionalProperties": false }, { "type": "null" } ] }, "tune": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "calibration_tune", "not_a_tune", "inconclusive", "not_applicable" ] }, "supportedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "coveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "a2lDefinedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "a2lDefinedCoveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "a2lDefinitionCoverageComplete": { "type": "boolean" } }, "required": [ "assessment", "supportedChangedBytes", "totalChangedBytes", "coveragePercent", "complete" ], "additionalProperties": false }, "unlock": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "ecu_unlock", "not_an_unlock", "inconclusive" ] }, "compatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "assessment", "compatibility", "totalChangedBytes", "complete" ], "additionalProperties": false }, "vehicle": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "matched", "conflicting", "inconclusive", "not_applicable" ] }, "researchStatus": { "type": "string", "enum": [ "available", "unavailable", "no_results", "not_attempted" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 1200 } }, "required": [ "status", "researchStatus", "explanation" ], "additionalProperties": false } }, "required": [ "version", "subjectVersionId", "stockVersionId", "a2lVersionId", "decision", "justification", "limitations", "evidenceKeys", "semanticMaps", "tune", "vehicle" ], "additionalProperties": false }, "bundleAssessment": { "type": "object", "properties": { "policyVersion": { "const": "tuning-bundle-v1" }, "stockVersionId": { "type": "string", "format": "uuid" }, "a2lVersionId": { "type": "string", "format": "uuid" }, "tunedVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "a2lCompatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "tuneAssessment": { "type": "string", "enum": [ "calibration_tune", "not_tune", "inconclusive", "not_applicable" ] }, "changedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "mappedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "comparisonPerformed": { "type": "boolean" }, "substantiveCalibrationChanges": { "type": "boolean" }, "hardConflicts": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 2, "maxItems": 32, "uniqueItems": true } }, "required": [ "policyVersion", "stockVersionId", "a2lVersionId", "tunedVersionId", "a2lCompatibility", "tuneAssessment", "changedBytes", "mappedChangedBytes", "comparisonPerformed", "substantiveCalibrationChanges", "hardConflicts", "evidenceKeys" ], "additionalProperties": false }, "findings": { "type": "object", "properties": { "format": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "ecuIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "softwareIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "vehicleFitment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "stockOriginality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "dependencyMatch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "integrity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "uniqueness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false } }, "required": [ "format", "ecuIdentity", "softwareIdentity", "vehicleFitment", "stockOriginality", "dependencyMatch", "integrity", "uniqueness" ], "additionalProperties": false }, "recommendation": { "type": "string", "enum": [ "needs_review", "reject", "failed_retryable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "evidenceKey": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "kind": { "type": "string", "enum": [ "byte_range", "parser_result", "checksum", "reference_match", "web_source", "staff_provenance", "comparison" ] }, "subjectVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "excerpt": { "type": "string", "minLength": 0, "maxLength": 8192 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 65536 }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "maxLength": 131072 }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 0, "maxLength": 2000 } }, "required": [ "name", "value" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "warnings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 0, "maxItems": 32 }, "checkedRanges": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 40 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] } }, "required": [ "address", "offset", "length", "status" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 } }, "required": [ "summary" ], "additionalProperties": false }, "sourceUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https?://" }, { "type": "null" } ] }, "sourceTitle": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sourceDigest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "evidenceKey", "kind", "subjectVersionId", "details", "sourceUrl", "sourceTitle", "retrievedAt", "sourceDigest", "expiresAt" ], "additionalProperties": false }, "minItems": 0, "maxItems": 128 }, "parserVersions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "name", "version" ], "additionalProperties": false }, "minItems": 0, "maxItems": 16 }, "profileVersions": { "type": "array", "items": { "type": "object", "properties": { "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "profileKey", "profileVersion" ], "additionalProperties": false }, "minItems": 0, "maxItems": 16 }, "modelId": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "promptVersion": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "fingerprints": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "exact_hash", "binary_equivalence", "a2l_structure" ] }, "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "kind", "profileKey", "profileVersion", "fingerprint" ], "additionalProperties": false }, "minItems": 0, "maxItems": 16 }, "dependencyMatches": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "resolvedVersionId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "role", "submittedVersionId", "resolvedVersionId", "status", "reasonCode", "evidenceKeys" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 65536 }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 100 }, "searches": { "type": "integer", "minimum": 0, "maximum": 20 }, "costMicros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})$", "description": "Decimal micro-units, at most 100000000." }, "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 900000 } }, "required": [ "inputTokens", "outputTokens", "toolCalls", "searches", "costMicros", "elapsedMs" ], "additionalProperties": false } }, "required": [ "findings", "recommendation", "reasonCode", "summary", "evidence", "parserVersions", "profileVersions", "modelId", "promptVersion", "policyVersion", "fingerprints", "dependencyMatches", "usage" ], "additionalProperties": false }, "WorkerResultRequest": { "type": "object", "properties": { "leaseToken": { "type": "string", "minLength": 32, "maxLength": 256, "pattern": "^[A-Za-z0-9_-]+$" }, "leaseGeneration": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "result": { "type": "object", "properties": { "tuningObservations": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "aggressive_calibration", "diagnostic_changes", "protection_changes", "limiter_changes", "other" ] }, "title": { "type": "string", "minLength": 8, "maxLength": 100 }, "detail": { "type": "string", "minLength": 20, "maxLength": 600 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 8 } }, "required": [ "category", "title", "detail", "evidenceKeys" ], "additionalProperties": false }, "minItems": 0, "maxItems": 8 }, "aiReview": { "type": "object", "properties": { "version": { "const": "tuning-ai-review.v1" }, "subjectVersionId": { "type": "string", "format": "uuid" }, "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "a2lVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "decision": { "type": "string", "enum": [ "approve", "review", "reject" ] }, "justification": { "type": "string", "minLength": 1, "maxLength": 1200 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 180 }, "minItems": 0, "maxItems": 8 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 1, "maxItems": 32, "uniqueItems": true }, "semanticMaps": { "anyOf": [ { "type": "object", "properties": { "declared": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "reviewed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "complete": { "type": "boolean" }, "supported": { "type": "integer", "minimum": 0, "maximum": 32768 }, "contradicted": { "type": "integer", "minimum": 0, "maximum": 32768 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "assessed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "supportedPercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "declared", "reviewed", "complete", "supported", "contradicted", "skipped", "assessed", "supportedPercent" ], "additionalProperties": false }, { "type": "null" } ] }, "tune": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "calibration_tune", "not_a_tune", "inconclusive", "not_applicable" ] }, "supportedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "coveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "a2lDefinedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "a2lDefinedCoveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "a2lDefinitionCoverageComplete": { "type": "boolean" } }, "required": [ "assessment", "supportedChangedBytes", "totalChangedBytes", "coveragePercent", "complete" ], "additionalProperties": false }, "unlock": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "ecu_unlock", "not_an_unlock", "inconclusive" ] }, "compatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "assessment", "compatibility", "totalChangedBytes", "complete" ], "additionalProperties": false }, "vehicle": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "matched", "conflicting", "inconclusive", "not_applicable" ] }, "researchStatus": { "type": "string", "enum": [ "available", "unavailable", "no_results", "not_attempted" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 1200 } }, "required": [ "status", "researchStatus", "explanation" ], "additionalProperties": false } }, "required": [ "version", "subjectVersionId", "stockVersionId", "a2lVersionId", "decision", "justification", "limitations", "evidenceKeys", "semanticMaps", "tune", "vehicle" ], "additionalProperties": false }, "bundleAssessment": { "type": "object", "properties": { "policyVersion": { "const": "tuning-bundle-v1" }, "stockVersionId": { "type": "string", "format": "uuid" }, "a2lVersionId": { "type": "string", "format": "uuid" }, "tunedVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "a2lCompatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "tuneAssessment": { "type": "string", "enum": [ "calibration_tune", "not_tune", "inconclusive", "not_applicable" ] }, "changedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "mappedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "comparisonPerformed": { "type": "boolean" }, "substantiveCalibrationChanges": { "type": "boolean" }, "hardConflicts": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 2, "maxItems": 32, "uniqueItems": true } }, "required": [ "policyVersion", "stockVersionId", "a2lVersionId", "tunedVersionId", "a2lCompatibility", "tuneAssessment", "changedBytes", "mappedChangedBytes", "comparisonPerformed", "substantiveCalibrationChanges", "hardConflicts", "evidenceKeys" ], "additionalProperties": false }, "findings": { "type": "object", "properties": { "format": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "ecuIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "softwareIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "vehicleFitment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "stockOriginality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "dependencyMatch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "integrity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "uniqueness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false } }, "required": [ "format", "ecuIdentity", "softwareIdentity", "vehicleFitment", "stockOriginality", "dependencyMatch", "integrity", "uniqueness" ], "additionalProperties": false }, "recommendation": { "type": "string", "enum": [ "needs_review", "reject", "failed_retryable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "evidenceKey": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "kind": { "type": "string", "enum": [ "byte_range", "parser_result", "checksum", "reference_match", "web_source", "staff_provenance", "comparison" ] }, "subjectVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "excerpt": { "type": "string", "minLength": 0, "maxLength": 8192 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 65536 }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "maxLength": 131072 }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 0, "maxLength": 2000 } }, "required": [ "name", "value" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "warnings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 0, "maxItems": 32 }, "checkedRanges": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 40 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] } }, "required": [ "address", "offset", "length", "status" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 } }, "required": [ "summary" ], "additionalProperties": false }, "sourceUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https?://" }, { "type": "null" } ] }, "sourceTitle": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sourceDigest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "evidenceKey", "kind", "subjectVersionId", "details", "sourceUrl", "sourceTitle", "retrievedAt", "sourceDigest", "expiresAt" ], "additionalProperties": false }, "minItems": 0, "maxItems": 128 }, "parserVersions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "name", "version" ], "additionalProperties": false }, "minItems": 0, "maxItems": 16 }, "profileVersions": { "type": "array", "items": { "type": "object", "properties": { "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "profileKey", "profileVersion" ], "additionalProperties": false }, "minItems": 0, "maxItems": 16 }, "modelId": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "promptVersion": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "fingerprints": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "exact_hash", "binary_equivalence", "a2l_structure" ] }, "profileKey": { "type": "string", "minLength": 1, "maxLength": 100 }, "profileVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "kind", "profileKey", "profileVersion", "fingerprint" ], "additionalProperties": false }, "minItems": 0, "maxItems": 16 }, "dependencyMatches": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "resolvedVersionId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "role", "submittedVersionId", "resolvedVersionId", "status", "reasonCode", "evidenceKeys" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "usage": { "type": "object", "properties": { "inputTokens": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 65536 }, "toolCalls": { "type": "integer", "minimum": 0, "maximum": 100 }, "searches": { "type": "integer", "minimum": 0, "maximum": 20 }, "costMicros": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,8})$", "description": "Decimal micro-units, at most 100000000." }, "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 900000 } }, "required": [ "inputTokens", "outputTokens", "toolCalls", "searches", "costMicros", "elapsedMs" ], "additionalProperties": false } }, "required": [ "findings", "recommendation", "reasonCode", "summary", "evidence", "parserVersions", "profileVersions", "modelId", "promptVersion", "policyVersion", "fingerprints", "dependencyMatches", "usage" ], "additionalProperties": false } }, "required": [ "leaseToken", "leaseGeneration", "result" ], "additionalProperties": false }, "KnownSoftwareRequest": { "type": "object", "properties": { "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 1, "maxItems": 16 } }, "required": [ "identifiers" ], "additionalProperties": false }, "KnownSoftwareResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "matches": { "type": "array", "items": { "type": "object", "properties": { "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "referenceVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sha256": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "trustedStock": { "type": "boolean" }, "vehicleFitments": { "type": "array", "items": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "yearFrom": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "yearTo": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "candidate", "verified" ] } }, "required": [ "make", "model", "variant", "engine", "yearFrom", "yearTo", "market", "status" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 } }, "required": [ "identifiers", "referenceVersionId", "sha256", "trustedStock", "vehicleFitments" ], "additionalProperties": false }, "minItems": 0, "maxItems": 20 }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "evidenceKey": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "kind": { "type": "string", "enum": [ "byte_range", "parser_result", "checksum", "reference_match", "web_source", "staff_provenance", "comparison" ] }, "subjectVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "excerpt": { "type": "string", "minLength": 0, "maxLength": 8192 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 65536 }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "maxLength": 131072 }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 0, "maxLength": 2000 } }, "required": [ "name", "value" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "warnings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 0, "maxItems": 32 }, "checkedRanges": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 40 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] } }, "required": [ "address", "offset", "length", "status" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 } }, "required": [ "summary" ], "additionalProperties": false }, "sourceUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https?://" }, { "type": "null" } ] }, "sourceTitle": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sourceDigest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "evidenceKey", "kind", "subjectVersionId", "details", "sourceUrl", "sourceTitle", "retrievedAt", "sourceDigest", "expiresAt" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 } }, "required": [ "matches", "evidence" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false }, "ContributionConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "minItems": 0, "maxItems": 3, "uniqueItems": true }, "limits": { "type": "object", "properties": { "maxBinBytes": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "maxA2lBytes": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "maxMultipartBytes": { "type": "integer", "minimum": 1, "maximum": 68157440 }, "maxMetadataBytes": { "type": "integer", "minimum": 1, "maximum": 65536 }, "maxItemsPerContribution": { "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "maxBinBytes", "maxA2lBytes", "maxMultipartBytes", "maxMetadataBytes", "maxItemsPerContribution" ], "additionalProperties": false }, "dependencyRules": { "type": "object", "properties": { "original_bin": { "type": "array", "items": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "minItems": 0, "maxItems": 0 }, "a2l": { "const": [ "stock_baseline" ] }, "tuned_bin": { "const": [ "stock_baseline", "matching_a2l" ] } }, "required": [ "original_bin", "a2l", "tuned_bin" ], "additionalProperties": false }, "dependencyRulesByModificationType": { "type": "object", "properties": { "unlocked": { "const": [ "stock_baseline" ] } }, "required": [ "unlocked" ], "additionalProperties": false }, "estimatedRewards": { "type": "object", "properties": { "original_bin": { "anyOf": [ { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, { "type": "null" } ] }, "a2l": { "anyOf": [ { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, { "type": "null" } ] }, "tuned_bin": { "anyOf": [ { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, { "type": "null" } ] } }, "required": [ "original_bin", "a2l", "tuned_bin" ], "additionalProperties": false }, "proposedRewards": { "type": "object", "properties": { "original_bin": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "a2l": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "tuned_bin": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" } }, "required": [ "original_bin", "a2l", "tuned_bin" ], "additionalProperties": false }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 0, "maxItems": 20 }, "rightsTerms": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "minLength": 1, "maxLength": 12000 } }, "required": [ "version", "text" ], "additionalProperties": false }, { "type": "null" } ] }, "multiDme": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "submissionReady": { "type": "boolean" }, "maxSets": { "const": 2 }, "maxRolesPerSet": { "const": 4 }, "dmeRoles": { "const": [ "single", "master", "slave" ] }, "fileRoles": { "const": [ "original", "a2l", "stage1", "stage2" ] }, "workerContextVersion": { "const": "2" } }, "required": [ "enabled", "submissionReady", "maxSets", "maxRolesPerSet", "dmeRoles", "fileRoles", "workerContextVersion" ], "additionalProperties": false } }, "required": [ "enabled", "kinds", "limits", "dependencyRules", "dependencyRulesByModificationType", "estimatedRewards", "proposedRewards", "limitations", "rightsTerms", "multiDme" ], "additionalProperties": false }, "ContributionDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "draft", "submitted", "processing", "complete", "cancelled" ] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "eventSequence": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "previousUpload": { "anyOf": [ { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "replacement", "dependency_recheck" ] } }, "required": [ "contributionId", "itemId", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "replacementUpload": { "anyOf": [ { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "replacement", "dependency_recheck" ] } }, "required": [ "contributionId", "itemId", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "replaceable": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "identityEnrichment": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "queued", "running", "retry_wait", "complete", "partial", "cancelled" ] }, "message": { "type": "string", "maxLength": 200 }, "updatedAt": { "type": "string", "format": "date-time" }, "identifiedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 }, "unresolvedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 } }, "required": [ "state", "message", "updatedAt", "identifiedFields", "unresolvedFields" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "fileId": { "type": "string", "format": "uuid" }, "clientItemId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "versionId": { "type": "string", "format": "uuid" }, "dmeContext": { "anyOf": [ { "type": "object", "properties": { "setId": { "type": "string", "format": "uuid" }, "clientSetId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "setId", "clientSetId", "dmeRole", "fileRole" ], "additionalProperties": false }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "originalFilename": { "type": "string", "minLength": 1, "maxLength": 255 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "tuningStage": { "anyOf": [ { "type": "string", "enum": [ "stage1", "stage2", "custom_stage3", "unlocked" ] }, { "type": "null" } ] }, "metadataEtag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "state": { "type": "string", "enum": [ "draft", "queued", "processing", "waiting_dependencies", "needs_review", "accepted", "duplicate", "rejected", "failed", "withdrawn" ] }, "reasonCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, { "type": "null" } ] }, "decisionSummary": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "publicationState": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "retryable": { "type": "boolean" }, "rewardState": { "type": "string", "enum": [ "pending", "awarded", "not_eligible", "reversed" ] }, "rewardAmount": { "anyOf": [ { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, { "type": "null" } ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "versionEtag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "latestVerificationRunId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "resolvedVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "matchState": { "type": "string", "enum": [ "pending", "verified", "rejected", "unknown" ] } }, "required": [ "role", "submittedVersionId", "resolvedVersionId", "matchState" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "job": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "queued", "running", "waiting_dependencies", "succeeded", "failed", "cancelled" ] }, "stage": { "type": "string", "enum": [ "queued", "inspect", "extract_identifiers", "integrity", "relationship", "evidence", "uniqueness", "finalize" ] }, "eventSequence": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "attemptCount": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "lastErrorCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, { "type": "null" } ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, "required": [ "id", "state", "stage", "eventSequence", "attemptCount", "lastErrorCode", "etag" ], "additionalProperties": false }, { "type": "null" } ] }, "findings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "ecuIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "softwareIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "vehicleFitment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "stockOriginality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "dependencyMatch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "integrity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "uniqueness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false } }, "required": [ "format", "ecuIdentity", "softwareIdentity", "vehicleFitment", "stockOriginality", "dependencyMatch", "integrity", "uniqueness" ], "additionalProperties": false }, { "type": "null" } ] }, "aiReview": { "anyOf": [ { "type": "object", "properties": { "version": { "const": "tuning-ai-review.v1" }, "decision": { "type": "string", "enum": [ "approve", "review", "reject" ] }, "justification": { "type": "string", "minLength": 1, "maxLength": 1200 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 180 }, "minItems": 0, "maxItems": 8 }, "semanticMaps": { "anyOf": [ { "type": "object", "properties": { "declared": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "reviewed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "complete": { "type": "boolean" }, "supported": { "type": "integer", "minimum": 0, "maximum": 32768 }, "contradicted": { "type": "integer", "minimum": 0, "maximum": 32768 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "assessed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "supportedPercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "declared", "reviewed", "complete", "supported", "contradicted", "skipped", "assessed", "supportedPercent" ], "additionalProperties": false }, { "type": "null" } ] }, "tune": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "calibration_tune", "not_a_tune", "inconclusive", "not_applicable" ] }, "supportedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "coveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "a2lDefinedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "a2lDefinedCoveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "a2lDefinitionCoverageComplete": { "type": "boolean" } }, "required": [ "assessment", "supportedChangedBytes", "totalChangedBytes", "coveragePercent", "complete" ], "additionalProperties": false }, "unlock": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "ecu_unlock", "not_an_unlock", "inconclusive" ] }, "compatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "assessment", "compatibility", "totalChangedBytes", "complete" ], "additionalProperties": false }, "vehicle": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "matched", "conflicting", "inconclusive", "not_applicable" ] }, "researchStatus": { "type": "string", "enum": [ "available", "unavailable", "no_results", "not_attempted" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 1200 } }, "required": [ "status", "researchStatus", "explanation" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "pattern": "^https?://" } }, "required": [ "title", "url" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 } }, "required": [ "version", "decision", "justification", "limitations", "semanticMaps", "tune", "vehicle", "sources" ], "additionalProperties": false }, { "type": "null" } ] }, "tuningObservations": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "aggressive_calibration", "diagnostic_changes", "protection_changes", "limiter_changes", "other" ] }, "title": { "type": "string", "minLength": 8, "maxLength": 100 }, "detail": { "type": "string", "minLength": 20, "maxLength": 600 } }, "required": [ "category", "title", "detail" ], "additionalProperties": false }, "minItems": 0, "maxItems": 8 }, "extractedIdentifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 200 }, { "type": "null" } ] }, "originalField": { "type": "string", "minLength": 0, "maxLength": 200 }, "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "string", "minLength": 1, "maxLength": 80 } ] }, "declared": { "type": "boolean" }, "interpretation": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "part_number", "hardware_identifier", "software_identifier", "software_version", "calibration_identifier", "bootloader_identifier", "engine_description", "ecu_family", "unknown" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "classification", "explanation" ], "additionalProperties": false } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset", "source" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "bundleAssessment": { "anyOf": [ { "type": "object", "properties": { "policyVersion": { "const": "tuning-bundle-v1" }, "a2lCompatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "tuneAssessment": { "type": "string", "enum": [ "calibration_tune", "not_tune", "inconclusive", "not_applicable" ] }, "changedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "mappedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "comparisonPerformed": { "type": "boolean" }, "substantiveCalibrationChanges": { "type": "boolean" }, "hasHardConflicts": { "type": "boolean" }, "mapAnalysisStatus": { "type": "string", "enum": [ "available", "unavailable", "unknown" ] } }, "required": [ "policyVersion", "a2lCompatibility", "tuneAssessment", "changedBytes", "mappedChangedBytes", "comparisonPerformed", "substantiveCalibrationChanges", "hasHardConflicts" ], "additionalProperties": false }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "evidenceKey": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "kind": { "type": "string", "enum": [ "byte_range", "parser_result", "checksum", "reference_match", "web_source", "staff_provenance", "comparison" ] }, "subjectVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "excerpt": { "type": "string", "minLength": 0, "maxLength": 8192 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 65536 }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "maxLength": 131072 }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 0, "maxLength": 2000 } }, "required": [ "name", "value" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "warnings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 0, "maxItems": 32 }, "checkedRanges": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 40 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] } }, "required": [ "address", "offset", "length", "status" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 } }, "required": [ "summary" ], "additionalProperties": false }, "sourceUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https?://" }, { "type": "null" } ] }, "sourceTitle": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sourceDigest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "evidenceKey", "kind", "subjectVersionId", "details", "sourceUrl", "sourceTitle", "retrievedAt", "sourceDigest", "expiresAt" ], "additionalProperties": false }, "minItems": 0, "maxItems": 128 } }, "required": [ "identityEnrichment", "id", "fileId", "clientItemId", "versionId", "kind", "originalFilename", "sha256", "byteSize", "claims", "state", "reasonCode", "decisionSummary", "publicationState", "retryable", "rewardState", "rewardAmount", "etag", "versionEtag", "latestVerificationRunId", "dependencies", "job", "findings", "evidence" ], "additionalProperties": false }, "minItems": 0, "maxItems": 20 } }, "required": [ "id", "state", "submittedAt", "completedAt", "cancelledAt", "createdAt", "updatedAt", "etag", "eventSequence", "items" ], "additionalProperties": false }, "ContributionItem": { "type": "object", "properties": { "previousUpload": { "anyOf": [ { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "replacement", "dependency_recheck" ] } }, "required": [ "contributionId", "itemId", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "replacementUpload": { "anyOf": [ { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "replacement", "dependency_recheck" ] } }, "required": [ "contributionId", "itemId", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "replaceable": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "identityEnrichment": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "queued", "running", "retry_wait", "complete", "partial", "cancelled" ] }, "message": { "type": "string", "maxLength": 200 }, "updatedAt": { "type": "string", "format": "date-time" }, "identifiedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 }, "unresolvedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 } }, "required": [ "state", "message", "updatedAt", "identifiedFields", "unresolvedFields" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "fileId": { "type": "string", "format": "uuid" }, "clientItemId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "versionId": { "type": "string", "format": "uuid" }, "dmeContext": { "anyOf": [ { "type": "object", "properties": { "setId": { "type": "string", "format": "uuid" }, "clientSetId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "setId", "clientSetId", "dmeRole", "fileRole" ], "additionalProperties": false }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "originalFilename": { "type": "string", "minLength": 1, "maxLength": 255 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "tuningStage": { "anyOf": [ { "type": "string", "enum": [ "stage1", "stage2", "custom_stage3", "unlocked" ] }, { "type": "null" } ] }, "metadataEtag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "state": { "type": "string", "enum": [ "draft", "queued", "processing", "waiting_dependencies", "needs_review", "accepted", "duplicate", "rejected", "failed", "withdrawn" ] }, "reasonCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, { "type": "null" } ] }, "decisionSummary": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "publicationState": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "retryable": { "type": "boolean" }, "rewardState": { "type": "string", "enum": [ "pending", "awarded", "not_eligible", "reversed" ] }, "rewardAmount": { "anyOf": [ { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, { "type": "null" } ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "versionEtag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "latestVerificationRunId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "resolvedVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "matchState": { "type": "string", "enum": [ "pending", "verified", "rejected", "unknown" ] } }, "required": [ "role", "submittedVersionId", "resolvedVersionId", "matchState" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "job": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "queued", "running", "waiting_dependencies", "succeeded", "failed", "cancelled" ] }, "stage": { "type": "string", "enum": [ "queued", "inspect", "extract_identifiers", "integrity", "relationship", "evidence", "uniqueness", "finalize" ] }, "eventSequence": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "attemptCount": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "lastErrorCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, { "type": "null" } ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, "required": [ "id", "state", "stage", "eventSequence", "attemptCount", "lastErrorCode", "etag" ], "additionalProperties": false }, { "type": "null" } ] }, "findings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "ecuIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "softwareIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "vehicleFitment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "stockOriginality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "dependencyMatch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "integrity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "uniqueness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false } }, "required": [ "format", "ecuIdentity", "softwareIdentity", "vehicleFitment", "stockOriginality", "dependencyMatch", "integrity", "uniqueness" ], "additionalProperties": false }, { "type": "null" } ] }, "aiReview": { "anyOf": [ { "type": "object", "properties": { "version": { "const": "tuning-ai-review.v1" }, "decision": { "type": "string", "enum": [ "approve", "review", "reject" ] }, "justification": { "type": "string", "minLength": 1, "maxLength": 1200 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 180 }, "minItems": 0, "maxItems": 8 }, "semanticMaps": { "anyOf": [ { "type": "object", "properties": { "declared": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "reviewed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "complete": { "type": "boolean" }, "supported": { "type": "integer", "minimum": 0, "maximum": 32768 }, "contradicted": { "type": "integer", "minimum": 0, "maximum": 32768 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "assessed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "supportedPercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "declared", "reviewed", "complete", "supported", "contradicted", "skipped", "assessed", "supportedPercent" ], "additionalProperties": false }, { "type": "null" } ] }, "tune": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "calibration_tune", "not_a_tune", "inconclusive", "not_applicable" ] }, "supportedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "coveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "a2lDefinedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "a2lDefinedCoveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "a2lDefinitionCoverageComplete": { "type": "boolean" } }, "required": [ "assessment", "supportedChangedBytes", "totalChangedBytes", "coveragePercent", "complete" ], "additionalProperties": false }, "unlock": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "ecu_unlock", "not_an_unlock", "inconclusive" ] }, "compatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "assessment", "compatibility", "totalChangedBytes", "complete" ], "additionalProperties": false }, "vehicle": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "matched", "conflicting", "inconclusive", "not_applicable" ] }, "researchStatus": { "type": "string", "enum": [ "available", "unavailable", "no_results", "not_attempted" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 1200 } }, "required": [ "status", "researchStatus", "explanation" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "pattern": "^https?://" } }, "required": [ "title", "url" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 } }, "required": [ "version", "decision", "justification", "limitations", "semanticMaps", "tune", "vehicle", "sources" ], "additionalProperties": false }, { "type": "null" } ] }, "tuningObservations": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "aggressive_calibration", "diagnostic_changes", "protection_changes", "limiter_changes", "other" ] }, "title": { "type": "string", "minLength": 8, "maxLength": 100 }, "detail": { "type": "string", "minLength": 20, "maxLength": 600 } }, "required": [ "category", "title", "detail" ], "additionalProperties": false }, "minItems": 0, "maxItems": 8 }, "extractedIdentifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 200 }, { "type": "null" } ] }, "originalField": { "type": "string", "minLength": 0, "maxLength": 200 }, "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "string", "minLength": 1, "maxLength": 80 } ] }, "declared": { "type": "boolean" }, "interpretation": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "part_number", "hardware_identifier", "software_identifier", "software_version", "calibration_identifier", "bootloader_identifier", "engine_description", "ecu_family", "unknown" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "classification", "explanation" ], "additionalProperties": false } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset", "source" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "bundleAssessment": { "anyOf": [ { "type": "object", "properties": { "policyVersion": { "const": "tuning-bundle-v1" }, "a2lCompatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "tuneAssessment": { "type": "string", "enum": [ "calibration_tune", "not_tune", "inconclusive", "not_applicable" ] }, "changedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "mappedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "comparisonPerformed": { "type": "boolean" }, "substantiveCalibrationChanges": { "type": "boolean" }, "hasHardConflicts": { "type": "boolean" }, "mapAnalysisStatus": { "type": "string", "enum": [ "available", "unavailable", "unknown" ] } }, "required": [ "policyVersion", "a2lCompatibility", "tuneAssessment", "changedBytes", "mappedChangedBytes", "comparisonPerformed", "substantiveCalibrationChanges", "hasHardConflicts" ], "additionalProperties": false }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "evidenceKey": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "kind": { "type": "string", "enum": [ "byte_range", "parser_result", "checksum", "reference_match", "web_source", "staff_provenance", "comparison" ] }, "subjectVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "excerpt": { "type": "string", "minLength": 0, "maxLength": 8192 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 65536 }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "maxLength": 131072 }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 0, "maxLength": 2000 } }, "required": [ "name", "value" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "warnings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 0, "maxItems": 32 }, "checkedRanges": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 40 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] } }, "required": [ "address", "offset", "length", "status" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 } }, "required": [ "summary" ], "additionalProperties": false }, "sourceUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https?://" }, { "type": "null" } ] }, "sourceTitle": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sourceDigest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "evidenceKey", "kind", "subjectVersionId", "details", "sourceUrl", "sourceTitle", "retrievedAt", "sourceDigest", "expiresAt" ], "additionalProperties": false }, "minItems": 0, "maxItems": 128 } }, "required": [ "identityEnrichment", "id", "fileId", "clientItemId", "versionId", "kind", "originalFilename", "sha256", "byteSize", "claims", "state", "reasonCode", "decisionSummary", "publicationState", "retryable", "rewardState", "rewardAmount", "etag", "versionEtag", "latestVerificationRunId", "dependencies", "job", "findings", "evidence" ], "additionalProperties": false }, "DependencyOption": { "type": "object", "properties": { "versionId": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "fileId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "versionLabel": { "type": "string", "minLength": 1, "maxLength": 80 }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "stockVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "versionId", "kind", "sha256", "byteSize", "fileId", "title", "versionLabel", "identifiers", "stockVersionId" ], "additionalProperties": false }, "CreatedContribution": { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "state": { "const": "draft" }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, "required": [ "contributionId", "state", "etag" ], "additionalProperties": false }, "UploadedItem": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "versionId": { "type": "string", "format": "uuid" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, "required": [ "itemId", "versionId", "sha256", "byteSize", "etag" ], "additionalProperties": false }, "SubmittedContribution": { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemStates": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "draft", "queued", "processing", "waiting_dependencies", "needs_review", "accepted", "duplicate", "rejected", "failed", "withdrawn" ] } }, "required": [ "itemId", "state" ], "additionalProperties": false }, "minItems": 0, "maxItems": 20 }, "jobIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 0, "maxItems": 20 } }, "required": [ "contributionId", "itemStates", "jobIds" ], "additionalProperties": false }, "RetriedItem": { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "queued", "running", "waiting_dependencies", "succeeded", "failed", "cancelled" ] } }, "required": [ "contributionId", "itemId", "jobId", "state" ], "additionalProperties": false }, "ReverifyItem": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "profileId": { "type": "string", "format": "uuid" }, "policyVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "restartInterrupted": { "type": "boolean" } }, "required": [ "reason" ], "additionalProperties": false }, "ProgressEvent": { "type": "object", "properties": { "contractVersion": { "const": "1" }, "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "jobId": { "type": "string", "format": "uuid" }, "sequence": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "stage": { "type": "string", "enum": [ "queued", "inspect", "extract_identifiers", "integrity", "relationship", "evidence", "uniqueness", "finalize" ] }, "itemState": { "type": "string", "enum": [ "draft", "queued", "processing", "waiting_dependencies", "needs_review", "accepted", "duplicate", "rejected", "failed", "withdrawn" ] }, "jobState": { "type": "string", "enum": [ "queued", "running", "waiting_dependencies", "succeeded", "failed", "cancelled" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "contractVersion", "contributionId", "itemId", "jobId", "sequence", "stage", "itemState", "jobState", "message", "occurredAt" ], "additionalProperties": false }, "ProfileActivation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "autoAcceptEnabled": { "type": "boolean" } }, "required": [ "enabled", "autoAcceptEnabled" ], "additionalProperties": false }, "VerificationProfile": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "profileKey": { "type": "string", "maxLength": 100 }, "profileVersion": { "type": "string", "maxLength": 80 }, "adapterKey": { "type": "string", "maxLength": 100 }, "kind": { "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "dumpLayout": { "type": "string", "maxLength": 100 }, "capabilities": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 100 } }, "enabled": { "type": "boolean" }, "autoAcceptEnabled": { "type": "boolean" }, "etag": { "type": "string", "maxLength": 40 } }, "required": [ "id", "profileKey", "profileVersion", "adapterKey", "kind", "dumpLayout", "capabilities", "enabled", "autoAcceptEnabled", "etag" ] }, "StaffContributionItem": { "type": "object", "properties": { "previousUpload": { "anyOf": [ { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "replacement", "dependency_recheck" ] } }, "required": [ "contributionId", "itemId", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "replacementUpload": { "anyOf": [ { "type": "object", "properties": { "contributionId": { "type": "string", "format": "uuid" }, "itemId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "enum": [ "replacement", "dependency_recheck" ] } }, "required": [ "contributionId", "itemId", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "replaceable": { "type": "boolean" }, "a2lChangedByteCoveragePercent": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "null" } ] }, "identityEnrichment": { "anyOf": [ { "type": "object", "properties": { "state": { "enum": [ "queued", "running", "retry_wait", "complete", "partial", "cancelled" ] }, "message": { "type": "string", "maxLength": 200 }, "updatedAt": { "type": "string", "format": "date-time" }, "identifiedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 }, "unresolvedFields": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 32 } }, "required": [ "state", "message", "updatedAt", "identifiedFields", "unresolvedFields" ], "additionalProperties": false }, { "type": "null" } ] }, "id": { "type": "string", "format": "uuid" }, "fileId": { "type": "string", "format": "uuid" }, "clientItemId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "versionId": { "type": "string", "format": "uuid" }, "dmeContext": { "anyOf": [ { "type": "object", "properties": { "setId": { "type": "string", "format": "uuid" }, "clientSetId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "dmeRole": { "type": "string", "enum": [ "single", "master", "slave" ] }, "fileRole": { "type": "string", "enum": [ "original", "a2l", "stage1", "stage2" ] } }, "required": [ "setId", "clientSetId", "dmeRole", "fileRole" ], "additionalProperties": false }, { "type": "null" } ] }, "kind": { "type": "string", "enum": [ "original_bin", "a2l", "tuned_bin" ] }, "originalFilename": { "type": "string", "minLength": 1, "maxLength": 255 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "byteSize": { "type": "string", "pattern": "^[1-9][0-9]{0,7}$", "description": "Decimal bytes, 1 through 67108864; deployment limits may be lower." }, "claims": { "type": "object", "properties": { "vehicle": { "type": "object", "properties": { "make": { "type": "string", "minLength": 1, "maxLength": 100 }, "model": { "type": "string", "minLength": 1, "maxLength": 100 }, "year": { "anyOf": [ { "type": "integer", "minimum": 1900, "maximum": 2200 }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "engine": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 100 }, { "type": "null" } ] }, "market": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "make", "model", "year", "variant", "engine", "market" ], "additionalProperties": false }, "ecu": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 160 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 }, "readType": { "type": "string", "enum": [ "full", "partial", "virtual", "unknown" ] }, "readMethod": { "type": "string", "enum": [ "obd", "bench", "boot", "other", "unknown" ] }, "readTool": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "provenance": { "type": "string", "minLength": 1, "maxLength": 4000 }, "permissionConfirmed": { "type": "boolean" }, "permissionTextVersion": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 }, "stage": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 80 }, { "type": "null" } ] }, "fuelRequirement": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 120 }, { "type": "null" } ] }, "hardwareRequirements": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 2000 }, { "type": "null" } ] }, "testingEvidence": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] } }, "required": [ "vehicle", "ecu", "description", "readType", "readMethod", "readTool", "provenance", "permissionConfirmed", "permissionTextVersion", "identifiers", "stage", "fuelRequirement", "hardwareRequirements", "testingEvidence" ], "additionalProperties": false }, "title": { "type": "string", "minLength": 1, "maxLength": 180 }, "description": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 10000 }, { "type": "null" } ] }, "tuningStage": { "anyOf": [ { "type": "string", "enum": [ "stage1", "stage2", "custom_stage3", "unlocked" ] }, { "type": "null" } ] }, "metadataEtag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "state": { "type": "string", "enum": [ "draft", "queued", "processing", "waiting_dependencies", "needs_review", "accepted", "duplicate", "rejected", "failed", "withdrawn" ] }, "reasonCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, { "type": "null" } ] }, "decisionSummary": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 4000 }, { "type": "null" } ] }, "publicationState": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "retryable": { "type": "boolean" }, "rewardState": { "type": "string", "enum": [ "pending", "awarded", "not_eligible", "reversed" ] }, "rewardAmount": { "anyOf": [ { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, { "type": "null" } ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "versionEtag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "latestVerificationRunId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "stock_baseline", "matching_a2l" ] }, "submittedVersionId": { "type": "string", "format": "uuid" }, "resolvedVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "matchState": { "type": "string", "enum": [ "pending", "verified", "rejected", "unknown" ] } }, "required": [ "role", "submittedVersionId", "resolvedVersionId", "matchState" ], "additionalProperties": false }, "minItems": 0, "maxItems": 2 }, "job": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "queued", "running", "waiting_dependencies", "succeeded", "failed", "cancelled" ] }, "stage": { "type": "string", "enum": [ "queued", "inspect", "extract_identifiers", "integrity", "relationship", "evidence", "uniqueness", "finalize" ] }, "eventSequence": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "attemptCount": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "lastErrorCode": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, { "type": "null" } ] }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" } }, "required": [ "id", "state", "stage", "eventSequence", "attemptCount", "lastErrorCode", "etag" ], "additionalProperties": false }, { "type": "null" } ] }, "findings": { "anyOf": [ { "type": "object", "properties": { "format": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "ecuIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "softwareIdentity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "vehicleFitment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "stockOriginality": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "dependencyMatch": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "integrity": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false }, "uniqueness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] }, "reasonCode": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,79}$" }, "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "evidenceKeys": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "minItems": 0, "maxItems": 32, "uniqueItems": true } }, "required": [ "status", "reasonCode", "summary", "evidenceKeys" ], "additionalProperties": false } }, "required": [ "format", "ecuIdentity", "softwareIdentity", "vehicleFitment", "stockOriginality", "dependencyMatch", "integrity", "uniqueness" ], "additionalProperties": false }, { "type": "null" } ] }, "aiReview": { "anyOf": [ { "type": "object", "properties": { "version": { "const": "tuning-ai-review.v1" }, "decision": { "type": "string", "enum": [ "approve", "review", "reject" ] }, "justification": { "type": "string", "minLength": 1, "maxLength": 1200 }, "limitations": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 180 }, "minItems": 0, "maxItems": 8 }, "semanticMaps": { "anyOf": [ { "type": "object", "properties": { "declared": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "reviewed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "complete": { "type": "boolean" }, "supported": { "type": "integer", "minimum": 0, "maximum": 32768 }, "contradicted": { "type": "integer", "minimum": 0, "maximum": 32768 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "assessed": { "type": "integer", "minimum": 0, "maximum": 32768 }, "supportedPercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "declared", "reviewed", "complete", "supported", "contradicted", "skipped", "assessed", "supportedPercent" ], "additionalProperties": false }, { "type": "null" } ] }, "tune": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "calibration_tune", "not_a_tune", "inconclusive", "not_applicable" ] }, "supportedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "coveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "complete": { "type": "boolean" }, "a2lDefinedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "a2lDefinedCoveragePercent": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] }, "a2lDefinitionCoverageComplete": { "type": "boolean" } }, "required": [ "assessment", "supportedChangedBytes", "totalChangedBytes", "coveragePercent", "complete" ], "additionalProperties": false }, "unlock": { "type": "object", "properties": { "assessment": { "type": "string", "enum": [ "ecu_unlock", "not_an_unlock", "inconclusive" ] }, "compatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "totalChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "complete": { "type": "boolean" } }, "required": [ "assessment", "compatibility", "totalChangedBytes", "complete" ], "additionalProperties": false }, "vehicle": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "matched", "conflicting", "inconclusive", "not_applicable" ] }, "researchStatus": { "type": "string", "enum": [ "available", "unavailable", "no_results", "not_attempted" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 1200 } }, "required": [ "status", "researchStatus", "explanation" ], "additionalProperties": false }, "sources": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "pattern": "^https?://" } }, "required": [ "title", "url" ], "additionalProperties": false }, "minItems": 0, "maxItems": 32 } }, "required": [ "version", "decision", "justification", "limitations", "semanticMaps", "tune", "vehicle", "sources" ], "additionalProperties": false }, { "type": "null" } ] }, "tuningObservations": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "aggressive_calibration", "diagnostic_changes", "protection_changes", "limiter_changes", "other" ] }, "title": { "type": "string", "minLength": 8, "maxLength": 100 }, "detail": { "type": "string", "minLength": 20, "maxLength": 600 } }, "required": [ "category", "title", "detail" ], "additionalProperties": false }, "minItems": 0, "maxItems": 8 }, "extractedIdentifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 200 }, { "type": "null" } ] }, "originalField": { "type": "string", "minLength": 0, "maxLength": 200 }, "confidence": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "string", "minLength": 1, "maxLength": 80 } ] }, "declared": { "type": "boolean" }, "interpretation": { "type": "object", "properties": { "classification": { "type": "string", "enum": [ "part_number", "hardware_identifier", "software_identifier", "software_version", "calibration_identifier", "bootloader_identifier", "engine_description", "ecu_family", "unknown" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "classification", "explanation" ], "additionalProperties": false } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset", "source" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "bundleAssessment": { "anyOf": [ { "type": "object", "properties": { "policyVersion": { "const": "tuning-bundle-v1" }, "a2lCompatibility": { "type": "string", "enum": [ "compatible", "incompatible", "inconclusive" ] }, "tuneAssessment": { "type": "string", "enum": [ "calibration_tune", "not_tune", "inconclusive", "not_applicable" ] }, "changedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "mappedChangedBytes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108864 }, { "type": "null" } ] }, "comparisonPerformed": { "type": "boolean" }, "substantiveCalibrationChanges": { "type": "boolean" }, "hasHardConflicts": { "type": "boolean" }, "mapAnalysisStatus": { "type": "string", "enum": [ "available", "unavailable", "unknown" ] } }, "required": [ "policyVersion", "a2lCompatibility", "tuneAssessment", "changedBytes", "mappedChangedBytes", "comparisonPerformed", "substantiveCalibrationChanges", "hasHardConflicts" ], "additionalProperties": false }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "evidenceKey": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$" }, "kind": { "type": "string", "enum": [ "byte_range", "parser_result", "checksum", "reference_match", "web_source", "staff_provenance", "comparison" ] }, "subjectVersionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "details": { "type": "object", "properties": { "summary": { "type": "string", "minLength": 1, "maxLength": 4000 }, "excerpt": { "type": "string", "minLength": 0, "maxLength": 8192 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 65536 }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "maxLength": 131072 }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "software_number", "software_version", "calibration_id", "hardware_number", "epk", "bootloader_id", "other" ] }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80 }, "rawValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "normalizedValue": { "type": "string", "minLength": 1, "maxLength": 255 }, "offset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 67108863 }, { "type": "null" } ] } }, "required": [ "kind", "namespace", "rawValue", "normalizedValue", "offset" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "minLength": 0, "maxLength": 2000 } }, "required": [ "name", "value" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 }, "warnings": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 0, "maxItems": 32 }, "checkedRanges": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "maxLength": 40 }, "offset": { "type": "integer", "minimum": 0, "maximum": 67108863 }, "length": { "type": "integer", "minimum": 1, "maximum": 67108864 }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown", "unsupported", "not_applicable" ] } }, "required": [ "address", "offset", "length", "status" ], "additionalProperties": false }, "minItems": 0, "maxItems": 64 } }, "required": [ "summary" ], "additionalProperties": false }, "sourceUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri", "pattern": "^https?://" }, { "type": "null" } ] }, "sourceTitle": { "anyOf": [ { "type": "string", "minLength": 0, "maxLength": 500 }, { "type": "null" } ] }, "retrievedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sourceDigest": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "evidenceKey", "kind", "subjectVersionId", "details", "sourceUrl", "sourceTitle", "retrievedAt", "sourceDigest", "expiresAt" ], "additionalProperties": false }, "minItems": 0, "maxItems": 128 }, "restartable": { "type": "boolean", "description": "An administrator may restart an interrupted check, including an expired worker lease, using restartInterrupted on reverify. Automatic retry limits do not block this explicit action." }, "checksumVerificationEnabled": { "type": "boolean", "description": "Whether ECU checksum failures currently block staff acceptance. Historical findings are preserved even when enforcement is disabled." }, "withdrawalState": { "enum": [ "active", "withdrawn" ] }, "dependencyReviewState": { "enum": [ "clear", "hold" ] }, "dependencyReviewReason": { "anyOf": [ { "type": "string", "maxLength": 10000 }, { "type": "null" } ] } }, "required": [ "identityEnrichment", "id", "fileId", "clientItemId", "versionId", "kind", "originalFilename", "sha256", "byteSize", "claims", "state", "reasonCode", "decisionSummary", "publicationState", "retryable", "rewardState", "rewardAmount", "etag", "versionEtag", "latestVerificationRunId", "dependencies", "job", "findings", "evidence", "restartable", "checksumVerificationEnabled", "withdrawalState", "dependencyReviewState", "dependencyReviewReason" ], "additionalProperties": false }, "ContributionReview": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "draft", "submitted", "processing", "complete", "cancelled" ] }, "submittedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "etag": { "type": "string", "pattern": "^\"[1-9][0-9]*\"$" }, "eventSequence": { "type": "string", "maxLength": 20, "pattern": "^(0|[1-9][0-9]{0,19})$" }, "items": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/StaffContributionItem" } }, "user": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "displayName": { "type": "string", "maxLength": 120 } }, "required": [ "id", "email", "displayName" ] } }, "required": [ "id", "state", "submittedAt", "completedAt", "cancelledAt", "createdAt", "updatedAt", "etag", "eventSequence", "items", "user" ], "additionalProperties": false }, "StaffReviewContext": { "type": "object", "additionalProperties": false, "properties": { "itemId": { "type": "string", "format": "uuid" }, "etag": { "type": "string", "maxLength": 40 }, "canApprove": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "maxLength": 100 }, "message": { "type": "string", "maxLength": 2000 }, "itemId": { "type": "string", "format": "uuid" }, "contributionId": { "type": "string", "format": "uuid" }, "fileId": { "type": "string", "format": "uuid" } }, "required": [ "code", "message" ] } }, "identity": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "software": { "type": "array", "items": { "type": "string", "maxLength": 255 } }, "ecuVariants": { "type": "array", "items": { "type": "string", "maxLength": 255 } }, "records": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "software", "ecuVariants", "records" ] }, { "type": "null" } ] }, "dependencies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "role": { "type": "string", "maxLength": 40 }, "filename": { "type": "string", "maxLength": 255 }, "available": { "type": "boolean" }, "itemId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "contributionId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "fileId": { "type": "string", "format": "uuid" }, "matchState": { "type": "string", "maxLength": 40 } }, "required": [ "role", "filename", "available", "itemId", "contributionId", "fileId", "matchState" ] } }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "maxLength": 100 }, "decision": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "actor": { "type": "string", "maxLength": 120 }, "occurredAt": { "type": "string", "format": "date-time" }, "policyVersion": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } }, "required": [ "id", "action", "decision", "reason", "actor", "occurredAt", "policyVersion" ] } } }, "required": [ "itemId", "etag", "canApprove", "blockers", "identity", "dependencies", "history" ] }, "VerificationHeartbeat": { "type": "object", "additionalProperties": false, "properties": { "leaseExpiresAt": { "type": "string", "format": "date-time" }, "aiResearchEnabled": { "type": "boolean" } }, "required": [ "leaseExpiresAt", "aiResearchEnabled" ] }, "VerificationCompletion": { "type": "object", "additionalProperties": false, "properties": { "jobId": { "type": "string", "format": "uuid" }, "runId": { "type": "string", "format": "uuid" }, "state": { "enum": [ "succeeded", "failed" ] } }, "required": [ "jobId", "runId", "state" ] }, "IdentityHeartbeat": { "type": "object", "additionalProperties": false, "properties": { "leaseExpiresAt": { "type": "string", "format": "date-time" } }, "required": [ "leaseExpiresAt" ] }, "IdentitySaved": { "type": "object", "additionalProperties": false, "properties": { "saved": { "type": "boolean" }, "state": { "enum": [ "running", "retry_wait", "complete", "partial" ] } }, "required": [ "saved", "state" ] }, "DeveloperKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string", "minLength": 1, "maxLength": 32 }, "permissions": { "type": "array", "items": { "enum": [ "uds:read", "uds:write", "tuning:read", "tuning:upload", "tuning:download", "tuning:spend", "uds:sensitive-read", "uds:artifact-read", "uds:approve", "uds:revise", "uds:redact", "uds:publish" ] } }, "disabled": { "type": "boolean" }, "adminDisabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "etag": { "type": "string", "minLength": 1, "maxLength": 32 }, "status": { "enum": [ "active", "disabled", "expired", "revoked" ] } }, "required": [ "id", "userId", "name", "prefix", "permissions", "disabled", "adminDisabled", "createdAt", "expiresAt", "revokedAt", "lastUsedAt", "etag", "status" ], "additionalProperties": false }, "DeveloperKeyCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string", "minLength": 1, "maxLength": 32 }, "permissions": { "type": "array", "items": { "enum": [ "uds:read", "uds:write", "tuning:read", "tuning:upload", "tuning:download", "tuning:spend", "uds:sensitive-read", "uds:artifact-read", "uds:approve", "uds:revise", "uds:redact", "uds:publish" ] } }, "disabled": { "type": "boolean" }, "adminDisabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "etag": { "type": "string", "minLength": 1, "maxLength": 32 }, "status": { "enum": [ "active", "disabled", "expired", "revoked" ] }, "secret": { "type": "string", "minLength": 1, "maxLength": 90, "writeOnly": false, "description": "Shown once. Never logged, cached, stored in the browser or returned by a later GET." } }, "required": [ "id", "userId", "name", "prefix", "permissions", "disabled", "adminDisabled", "createdAt", "expiresAt", "revokedAt", "lastUsedAt", "etag", "status", "secret" ], "additionalProperties": false }, "DeveloperKeyList": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "accountEnabled": { "type": "boolean" }, "baselinePermissions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "availablePermissions": { "type": "array", "items": { "enum": [ "tuning:read", "tuning:upload", "tuning:download", "tuning:spend", "uds:sensitive-read", "uds:artifact-read" ] } }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/DeveloperKey" } } }, "required": [ "enabled", "accountEnabled", "baselinePermissions", "availablePermissions", "keys" ], "additionalProperties": false }, "DeveloperKeyCreate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "permissions": { "type": "array", "items": { "enum": [ "tuning:read", "tuning:upload", "tuning:download", "tuning:spend", "uds:sensitive-read", "uds:artifact-read" ] } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "name", "permissions", "expiresInDays", "currentPassword" ], "additionalProperties": false }, "DeveloperKeyPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "permissions": { "type": "array", "items": { "enum": [ "tuning:read", "tuning:upload", "tuning:download", "tuning:spend", "uds:sensitive-read", "uds:artifact-read" ] } }, "disabled": { "type": "boolean" }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "currentPassword" ], "additionalProperties": false }, "DeveloperKeyRotate": { "type": "object", "properties": { "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "overlapMinutes": { "enum": [ 0, 10 ] }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "expiresInDays", "overlapMinutes", "currentPassword" ], "additionalProperties": false }, "DeveloperConfirmation": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "currentPassword" ], "additionalProperties": false }, "DeveloperAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "type": "string", "minLength": 1, "maxLength": 255 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "status": { "enum": [ "pending_verification", "active", "suspended" ] }, "etag": { "type": "string", "minLength": 1, "maxLength": 32 }, "apiAccessEnabled": { "type": "boolean" }, "requestsPerMinute": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "id", "displayName", "email", "role", "status", "etag", "apiAccessEnabled", "requestsPerMinute" ], "additionalProperties": false }, "DeveloperAccountPatch": { "type": "object", "properties": { "apiAccessEnabled": { "type": "boolean" }, "requestsPerMinute": { "type": "integer", "minimum": 1, "maximum": 10000 }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "apiAccessEnabled", "requestsPerMinute", "currentPassword", "reason" ], "additionalProperties": false }, "DeveloperAdminKeyPatch": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "enum": [ "tuning:read", "tuning:upload", "tuning:download", "tuning:spend", "uds:sensitive-read", "uds:artifact-read", "uds:approve", "uds:revise", "uds:redact", "uds:publish" ] } }, "disabled": { "type": "boolean" }, "revoke": { "type": "boolean" }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "permissions", "disabled", "currentPassword", "reason" ], "additionalProperties": false }, "UdsApiPolicy": { "type": "object", "properties": { "approve": { "type": "boolean" }, "revise": { "type": "boolean" }, "redact": { "type": "boolean" }, "publish": { "type": "boolean" }, "etag": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "approve", "revise", "redact", "publish", "etag" ], "additionalProperties": false }, "UdsApiPolicyPatch": { "type": "object", "properties": { "approve": { "type": "boolean" }, "revise": { "type": "boolean" }, "redact": { "type": "boolean" }, "publish": { "type": "boolean" }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "approve", "revise", "redact", "publish", "currentPassword", "reason" ], "additionalProperties": false }, "UdsAdministrativeGrant": { "type": "object", "properties": { "principalType": { "enum": [ "developer", "service", "firebase" ] }, "principalId": { "type": "string", "minLength": 1, "maxLength": 191 }, "scopeId": { "type": "string", "format": "uuid" }, "capabilities": { "type": "array", "maxItems": 4, "uniqueItems": true, "items": { "enum": [ "approve", "revise", "redact", "publish" ] } }, "disabled": { "type": "boolean" }, "currentPassword": { "type": "string", "minLength": 1, "maxLength": 256 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "principalType", "principalId", "scopeId", "capabilities", "disabled", "currentPassword", "reason" ], "additionalProperties": false }, "UdsApiAdministration": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/UdsApiPolicy" }, "scopes": { "type": "array", "items": { "type": "object" } }, "grants": { "type": "array", "items": { "type": "object" } }, "credentials": { "type": "array", "items": { "type": "object" } }, "events": { "type": "array", "items": { "type": "object" } } }, "required": [ "policy", "scopes", "grants", "credentials", "events" ], "additionalProperties": false }, "ForumMember": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "ForumEntity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "label": { "type": "string", "maxLength": 255 }, "fileId": { "type": [ "string", "null" ], "format": "uuid" }, "href": { "type": "string", "maxLength": 500 }, "source": { "enum": [ "catalogue", "discussion_context" ] }, "threadCount": { "type": "integer", "minimum": 0 }, "commentCount": { "type": "integer", "minimum": 0 }, "following": { "type": "boolean" }, "followId": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "id", "type", "label", "href", "source" ], "additionalProperties": false }, "ForumAttachment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 160 }, "mimeType": { "type": "string", "maxLength": 100 }, "byteSize": { "type": "integer", "minimum": 0 }, "path": { "type": "string", "maxLength": 200 } }, "required": [ "id", "filename", "mimeType", "byteSize" ], "additionalProperties": false }, "ForumPost": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "maxLength": 30000 }, "author": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "editedAt": { "type": [ "string", "null" ], "format": "date-time" }, "helpfulCount": { "type": "integer", "minimum": 0 }, "helpful": { "type": "boolean" }, "deleted": { "type": "boolean" }, "etag": { "type": "string", "maxLength": 30 }, "parentId": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ] }, "entityId": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 160 }, "mimeType": { "type": "string", "maxLength": 100 }, "byteSize": { "type": "integer", "minimum": 0 }, "path": { "type": "string", "maxLength": 200 } }, "required": [ "id", "filename", "mimeType", "byteSize" ], "additionalProperties": false } } }, "required": [ "id", "body", "author", "etag" ], "additionalProperties": false }, "ForumThread": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "maxLength": 30000 }, "author": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "editedAt": { "type": [ "string", "null" ], "format": "date-time" }, "helpfulCount": { "type": "integer", "minimum": 0 }, "helpful": { "type": "boolean" }, "deleted": { "type": "boolean" }, "etag": { "type": "string", "maxLength": 30 }, "parentId": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ] }, "entityId": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 160 }, "mimeType": { "type": "string", "maxLength": 100 }, "byteSize": { "type": "integer", "minimum": 0 }, "path": { "type": "string", "maxLength": 200 } }, "required": [ "id", "filename", "mimeType", "byteSize" ], "additionalProperties": false } }, "title": { "type": "string", "maxLength": 180 }, "slug": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 500 }, "excerpt": { "type": "string", "maxLength": 600 }, "topic": { "enum": [ "reverse-engineering", "calibration", "flashing", "diagnostics", "files", "development", "general" ] }, "topicLabel": { "type": "string", "maxLength": 255 }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastContributor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "replyCount": { "type": "integer", "minimum": 0 }, "viewCount": { "type": "string", "pattern": "^[0-9]+$" }, "contributorCount": { "type": "integer", "minimum": 0 }, "pinned": { "type": "boolean" }, "locked": { "type": "boolean" }, "archived": { "type": "boolean" }, "solved": { "type": "boolean" }, "acceptedReplyId": { "type": [ "string", "null" ] }, "originFileId": { "type": [ "string", "null" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "label": { "type": "string", "maxLength": 255 }, "fileId": { "type": [ "string", "null" ], "format": "uuid" }, "href": { "type": "string", "maxLength": 500 }, "source": { "enum": [ "catalogue", "discussion_context" ] }, "threadCount": { "type": "integer", "minimum": 0 }, "commentCount": { "type": "integer", "minimum": 0 }, "following": { "type": "boolean" }, "followId": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "id", "type", "label", "href", "source" ], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "following": { "type": "boolean" }, "followId": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "href", "author", "entities", "tags", "etag" ], "additionalProperties": false }, "ForumThreadDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "maxLength": 30000 }, "author": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "editedAt": { "type": [ "string", "null" ], "format": "date-time" }, "helpfulCount": { "type": "integer", "minimum": 0 }, "helpful": { "type": "boolean" }, "deleted": { "type": "boolean" }, "etag": { "type": "string", "maxLength": 30 }, "parentId": { "type": [ "string", "null" ] }, "threadId": { "type": [ "string", "null" ] }, "entityId": { "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string", "maxLength": 160 }, "mimeType": { "type": "string", "maxLength": 100 }, "byteSize": { "type": "integer", "minimum": 0 }, "path": { "type": "string", "maxLength": 200 } }, "required": [ "id", "filename", "mimeType", "byteSize" ], "additionalProperties": false } }, "title": { "type": "string", "maxLength": 180 }, "slug": { "type": "string", "maxLength": 200 }, "href": { "type": "string", "maxLength": 500 }, "excerpt": { "type": "string", "maxLength": 600 }, "topic": { "enum": [ "reverse-engineering", "calibration", "flashing", "diagnostics", "files", "development", "general" ] }, "topicLabel": { "type": "string", "maxLength": 255 }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastActivityAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastContributor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, "replyCount": { "type": "integer", "minimum": 0 }, "viewCount": { "type": "string", "pattern": "^[0-9]+$" }, "contributorCount": { "type": "integer", "minimum": 0 }, "pinned": { "type": "boolean" }, "locked": { "type": "boolean" }, "archived": { "type": "boolean" }, "solved": { "type": "boolean" }, "acceptedReplyId": { "type": [ "string", "null" ] }, "originFileId": { "type": [ "string", "null" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "label": { "type": "string", "maxLength": 255 }, "fileId": { "type": [ "string", "null" ], "format": "uuid" }, "href": { "type": "string", "maxLength": 500 }, "source": { "enum": [ "catalogue", "discussion_context" ] }, "threadCount": { "type": "integer", "minimum": 0 }, "commentCount": { "type": "integer", "minimum": 0 }, "following": { "type": "boolean" }, "followId": { "type": [ "string", "null" ] }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "id", "type", "label", "href", "source" ], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 } }, "following": { "type": "boolean" }, "followId": { "type": [ "string", "null" ] }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/ForumPost" } }, "repliesPage": { "$ref": "#/components/schemas/Page" }, "acceptedReply": { "anyOf": [ { "$ref": "#/components/schemas/ForumPost" }, { "type": "null" } ] } }, "required": [ "id", "title", "body", "replies", "repliesPage" ], "additionalProperties": false }, "ForumWriteThread": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 180, "minLength": 8 }, "body": { "type": "string", "maxLength": 30000, "minLength": 20 }, "topic": { "enum": [ "reverse-engineering", "calibration", "flashing", "diagnostics", "files", "development", "general" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "value": { "type": "string", "maxLength": 255 }, "sourceId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "maxItems": 16 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 }, "maxItems": 5 }, "originFileId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 500 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "title", "body", "topic" ], "additionalProperties": false }, "ForumWritePost": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 20000, "minLength": 2 }, "parentId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 500 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "body" ], "additionalProperties": false }, "ForumChange": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "href": { "type": "string", "maxLength": 500 }, "threadId": { "type": "string", "format": "uuid" }, "entityId": { "type": "string", "format": "uuid" }, "following": { "type": "boolean" }, "helpful": { "type": "boolean" }, "helpfulCount": { "type": "integer", "minimum": 0 }, "acceptedReplyId": { "type": [ "string", "null" ] }, "deleted": { "type": "boolean" }, "action": { "type": "string", "maxLength": 40 }, "reported": { "type": "boolean" }, "read": { "type": "boolean" }, "recorded": { "type": "boolean" }, "handle": { "type": "string", "maxLength": 32 } }, "required": [], "additionalProperties": false }, "ForumNotification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "maxLength": 40 }, "title": { "type": "string", "maxLength": 255 }, "actor": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "displayName": { "type": "string", "maxLength": 120 }, "handle": { "type": "string", "maxLength": 32 }, "role": { "enum": [ "customer", "editor", "admin" ] }, "joinedAt": { "type": [ "string", "null" ], "format": "date-time" }, "bio": { "type": "string", "maxLength": 500 }, "reputation": { "type": "integer", "minimum": 0 }, "threads": { "type": "integer", "minimum": 0 }, "replies": { "type": "integer", "minimum": 0 }, "helpful": { "type": "integer", "minimum": 0 }, "acceptedAnswers": { "type": "integer", "minimum": 0 }, "filesContributed": { "type": "integer", "minimum": 0 }, "definitionsContributed": { "type": "integer", "minimum": 0 }, "etag": { "type": "string", "maxLength": 30 }, "restricted": { "type": "boolean" } }, "required": [ "id", "displayName", "handle", "reputation" ], "additionalProperties": false }, { "type": "null" } ] }, "href": { "type": "string", "maxLength": 500 }, "read": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "kind", "title", "actor", "href", "read", "createdAt" ], "additionalProperties": false }, "ForumCreateThread": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 180, "minLength": 8 }, "body": { "type": "string", "maxLength": 30000, "minLength": 20 }, "topic": { "enum": [ "reverse-engineering", "calibration", "flashing", "diagnostics", "files", "development", "general" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "value": { "type": "string", "maxLength": 255 }, "sourceId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "maxItems": 16 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 }, "maxItems": 5 }, "originFileId": { "type": "string", "format": "uuid" }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "title", "body", "topic" ], "additionalProperties": false }, "ForumEditThread": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 180, "minLength": 8 }, "body": { "type": "string", "maxLength": 30000, "minLength": 20 }, "topic": { "enum": [ "reverse-engineering", "calibration", "flashing", "diagnostics", "files", "development", "general" ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "ecu_manufacturer", "ecu_family", "vehicle_make", "vehicle_model", "vehicle_generation", "vehicle_year", "engine", "transmission", "software", "calibration", "hardware", "stock_file", "tuned_file", "a2l", "document", "tooling" ] }, "value": { "type": "string", "maxLength": 255 }, "sourceId": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "maxItems": 16 }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 }, "maxItems": 5 }, "reason": { "type": "string", "maxLength": 500 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "title", "body", "topic" ], "additionalProperties": false }, "ForumCreatePost": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 20000, "minLength": 2 }, "parentId": { "type": "string", "format": "uuid" }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "body" ], "additionalProperties": false }, "ForumEditPost": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 20000, "minLength": 2 }, "reason": { "type": "string", "maxLength": 500 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "body" ], "additionalProperties": false }, "ForumCreateComment": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 5000, "minLength": 2 }, "parentId": { "type": "string", "format": "uuid" }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "body" ], "additionalProperties": false }, "ForumEditComment": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 5000, "minLength": 2 }, "reason": { "type": "string", "maxLength": 500 }, "attachmentIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "body" ], "additionalProperties": false } } }, "externalDocs": { "url": "https://api.redlineautohaus.com/docs/tuning/", "description": "Read-only interactive reference, contract guide and runnable examples." }, "x-required-operations": [ "DELETE /contributions/{id}/items/{itemId}", "DELETE /forum/attachments/{id}", "DELETE /forum/comments/{id}", "DELETE /forum/follows/{id}", "DELETE /forum/replies/{id}", "DELETE /forum/threads/{id}", "DELETE /forum/{type}/{id}/reactions", "DELETE /me/api-keys/{id}", "DELETE /me/sessions/{sessionId}", "GET /admin/api-access/keys", "GET /admin/api-access/uds", "GET /admin/api-access/users", "GET /admin/audit-events", "GET /admin/catalog/ecu-manufacturers", "GET /admin/catalog/ecu-manufacturers/{id}", "GET /admin/catalog/ecu-types", "GET /admin/catalog/ecu-types/{id}", "GET /admin/catalog/vehicle-makes", "GET /admin/catalog/vehicle-makes/{id}", "GET /admin/catalog/vehicle-models", "GET /admin/catalog/vehicle-models/{id}", "GET /admin/catalog/vehicle-variants", "GET /admin/catalog/vehicle-variants/{id}", "GET /admin/contribution-items/{itemId}/duplicate-candidates", "GET /admin/contribution-items/{itemId}/review-context", "GET /admin/contribution-reviews", "GET /admin/contributions/{id}", "GET /admin/credit-ledger", "GET /admin/credit-policies", "GET /admin/credits", "GET /admin/download-acquisitions", "GET /admin/files", "GET /admin/files/{fileId}", "GET /admin/files/{fileId}/versions", "GET /admin/files/{fileId}/versions/{versionId}", "GET /admin/files/{fileId}/versions/{versionId}/download", "GET /admin/grants/{grantId}", "GET /admin/purchases/reconciliation", "GET /admin/purchases/{orderId}/reconciliation", "GET /admin/reward-claims", "GET /admin/site", "GET /admin/software-releases", "GET /admin/software-releases/{releaseId}", "GET /admin/users", "GET /admin/users/{userId}", "GET /admin/users/{userId}/company-verification", "GET /admin/users/{userId}/grants", "GET /admin/verification-profiles", "GET /auth/session", "GET /catalog/ecu-manufacturers", "GET /catalog/ecu-types", "GET /catalog/vehicle-makes", "GET /catalog/vehicle-models", "GET /catalog/vehicle-variants", "GET /contribution-config", "GET /contribution-dependencies", "GET /contributions", "GET /contributions/{id}", "GET /contributions/{id}/events", "GET /credits/packs", "GET /files", "GET /files/facets", "GET /files/{fileId}", "GET /files/{fileId}/download", "GET /files/{fileId}/related", "GET /files/{fileId}/versions/{versionId}/download", "GET /forum/attachments/{id}", "GET /forum/config", "GET /forum/context", "GET /forum/entities", "GET /forum/entities/{id}", "GET /forum/entities/{id}/comments", "GET /forum/entities/{id}/threads", "GET /forum/files/{id}/discussions", "GET /forum/following", "GET /forum/me/profile", "GET /forum/members", "GET /forum/members/{handle}", "GET /forum/moderation/analytics", "GET /forum/moderation/content", "GET /forum/moderation/history", "GET /forum/moderation/reports", "GET /forum/moderation/{type}/{id}/revisions", "GET /forum/notifications", "GET /forum/threads", "GET /forum/threads/{id}", "GET /forum/threads/{id}/entities", "GET /forum/threads/{id}/replies", "GET /me", "GET /me/acquisitions", "GET /me/api-keys", "GET /me/company-verification", "GET /me/credits", "GET /me/credits/ledger", "GET /me/downloads", "GET /me/grants", "GET /me/purchases", "GET /me/purchases/{orderId}", "GET /me/sessions", "GET /site", "GET /software-releases", "GET /software-releases/{releaseId}", "PATCH /admin/api-access/keys/{id}", "PATCH /admin/api-access/uds", "PATCH /admin/api-access/users/{id}", "PATCH /admin/catalog/ecu-manufacturers/{id}", "PATCH /admin/catalog/ecu-types/{id}", "PATCH /admin/catalog/vehicle-makes/{id}", "PATCH /admin/catalog/vehicle-models/{id}", "PATCH /admin/catalog/vehicle-variants/{id}", "PATCH /admin/credits/{userId}/restriction", "PATCH /admin/files/{fileId}", "PATCH /admin/files/{fileId}/versions/{versionId}", "PATCH /admin/grants/{grantId}", "PATCH /admin/site", "PATCH /admin/software-releases/{releaseId}", "PATCH /admin/users/{userId}", "PATCH /admin/verification-profiles/{id}", "PATCH /contributions/{id}/items/{itemId}", "PATCH /contributions/{id}/items/{itemId}/metadata", "PATCH /forum/comments/{id}", "PATCH /forum/me/profile", "PATCH /forum/moderation/reports/{id}", "PATCH /forum/notifications/read", "PATCH /forum/replies/{id}", "PATCH /forum/threads/{id}", "PATCH /me", "PATCH /me/api-keys/{id}", "POST /admin/catalog/ecu-manufacturers", "POST /admin/catalog/ecu-types", "POST /admin/catalog/vehicle-makes", "POST /admin/catalog/vehicle-models", "POST /admin/catalog/vehicle-variants", "POST /admin/contribution-items/{itemId}/decision", "POST /admin/contribution-items/{itemId}/equivalence", "POST /admin/contribution-items/{itemId}/evidence", "POST /admin/contribution-items/{itemId}/reverify", "POST /admin/credit-adjustments", "POST /admin/credit-policies", "POST /admin/credit-policies/{id}/activate", "POST /admin/download-acquisitions/{id}/refund", "POST /admin/file-versions/{versionId}/credit-review", "POST /admin/file-versions/{versionId}/stock-associations", "POST /admin/file-versions/{versionId}/withdraw", "POST /admin/files", "POST /admin/files/{fileId}/archive", "POST /admin/files/{fileId}/publish", "POST /admin/files/{fileId}/versions", "POST /admin/files/{fileId}/versions/{versionId}/review", "POST /admin/purchases/{orderId}/resolutions", "POST /admin/reward-claims/{id}/reverse", "POST /admin/software-releases", "POST /admin/users/{userId}/company-verification", "POST /admin/users/{userId}/grants", "POST /auth/forgot-password", "POST /auth/login", "POST /auth/logout", "POST /auth/logout-all", "POST /auth/register", "POST /auth/resend-verification", "POST /auth/reset-password", "POST /auth/verify-email", "POST /contributions", "POST /contributions/{id}/cancel", "POST /contributions/{id}/items", "POST /contributions/{id}/items/{itemId}/replace", "POST /contributions/{id}/items/{itemId}/retry", "POST /contributions/{id}/submit", "POST /credits/checkout", "POST /download-acquisitions", "POST /files/{fileId}/download-quote", "POST /forum/analytics", "POST /forum/attachments", "POST /forum/entities", "POST /forum/entities/{id}/comments", "POST /forum/follows", "POST /forum/moderation/users/{id}/sanction", "POST /forum/moderation/{type}/{id}/actions", "POST /forum/reports", "POST /forum/threads", "POST /forum/threads/{id}/replies", "POST /forum/{type}/{id}/reactions", "POST /me/api-keys", "POST /me/api-keys/revoke-all", "POST /me/api-keys/{id}/rotate", "POST /me/change-password", "POST /stripe/webhook", "PUT /admin/api-access/uds/grants", "PUT /admin/files/{fileId}/versions/{versionId}/relations", "PUT /admin/files/{fileId}/versions/{versionId}/releases", "PUT /admin/software-releases/{releaseId}/identifiers", "PUT /admin/software-releases/{releaseId}/vehicle-fitments", "PUT /contributions/{id}/items/{itemId}/dependencies", "PUT /forum/threads/{id}/entities", "PUT /forum/threads/{id}/solution" ] }