{ "openapi": "3.1.0", "info": { "title": "Localisync Diagnostics", "version": "1.0.0", "description": "Optional SDK diagnostics and write-only credential management. Operator monitoring is private." }, "paths": { "/api/v1/workspaces/{workspaceId}/projects/{projectId}/distributions/{id}/diagnostic-keys": { "get": { "operationId": "listDiagnosticKeys", "summary": "List diagnostic key metadata", "description": "Owner/Admin only; current membership and active workspace/project are required for changes. Secrets are returned once and stored only as hashes. A lost creation response requires revocation and a new key. No customer error-list access is granted.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "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": "Operation succeeded. A repeated create returns secret=null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticKeyPage" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid schema or expired event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Session or diagnostic credential rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient role or origin/CSRF rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 32 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or concurrency limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected application failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or Collector unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createDiagnosticKey", "summary": "Create a write-only diagnostic key", "description": "Owner/Admin only; current membership and active workspace/project are required for changes. Secrets are returned once and stored only as hashes. A lost creation response requires revocation and a new key. No customer error-list access is granted.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticKeyInput" } } } }, "responses": { "201": { "description": "Operation succeeded. A repeated create returns secret=null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticKeyResult" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid schema or expired event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Session or diagnostic credential rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient role or origin/CSRF rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 32 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or concurrency limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected application failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or Collector unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/distributions/{id}/diagnostic-keys/{keyId}/revoke": { "post": { "operationId": "revokeDiagnosticKey", "summary": "Revoke a diagnostic key", "description": "Owner/Admin only; current membership and active workspace/project are required for changes. Secrets are returned once and stored only as hashes. A lost creation response requires revocation and a new key. No customer error-list access is granted.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "responses": { "200": { "description": "Operation succeeded. A repeated create returns secret=null.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnosticKey" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid schema or expired event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Session or diagnostic credential rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient role or origin/CSRF rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 32 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or concurrency limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected application failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or Collector unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/telemetry/v1/sdk-events": { "post": { "operationId": "submitSdkDiagnostics", "summary": "Submit a bounded batch of SDK diagnostics", "description": "Opt-in SDK diagnostics only. Dedicated bearer key derives distribution/channel scope; read keys and cookies do not authorize this operation. Exact distribution origins apply in browsers. Maximum 20 events / 32 KiB; events expire after 15 minutes. Global 1000, IP 120 and key 60 requests/minute plus 8 concurrent requests per API process. Client reports are untrusted.", "security": [ { "diagnosticKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkBatch" } } } }, "responses": { "202": { "description": "Collector accepted the batch; this is not a guarantee of durable storage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } }, "headers": { "X-Request-ID": { "schema": { "type": "string", "format": "uuid" } } } }, "400": { "description": "Invalid schema or expired event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Session or diagnostic credential rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient role or origin/CSRF rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource is not accessible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds 32 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request or concurrency limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected application failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency or Collector unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "DiagnosticKey": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "channel": { "type": "string", "enum": [ "preview", "production" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "label", "channel", "id", "version", "createdAt", "revokedAt" ], "additionalProperties": false }, "DiagnosticKeyInput": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "channel": { "type": "string", "enum": [ "preview", "production" ] } }, "required": [ "label", "channel" ], "additionalProperties": false }, "DiagnosticKeyPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "channel": { "type": "string", "enum": [ "preview", "production" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "label", "channel", "id", "version", "createdAt", "revokedAt" ], "additionalProperties": false } }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ] }, "DiagnosticKeyResult": { "type": "object", "properties": { "key": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "channel": { "type": "string", "enum": [ "preview", "production" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "label", "channel", "id", "version", "createdAt", "revokedAt" ], "additionalProperties": false }, "secret": { "type": [ "string", "null" ] } }, "required": [ "key", "secret" ] }, "Version": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "version" ], "additionalProperties": false }, "SdkBatch": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "events": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "sdk": { "type": "string", "enum": [ "web", "flutter" ] }, "sdkVersion": { "type": "string", "maxLength": 80, "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$" }, "appVersion": { "type": "string", "maxLength": 100, "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$" }, "code": { "type": "string", "enum": [ "configuration", "network", "timeout", "authorization", "verification", "integrity", "protocol", "compatibility", "incompatible", "staleRevision", "storage", "worker", "arguments", "locale" ] }, "stage": { "type": "string", "enum": [ "start", "refresh", "locale", "activate", "translate", "cache", "worker" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "releaseId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "observedAt", "sdk", "sdkVersion", "appVersion", "code", "stage", "count" ], "additionalProperties": false } } }, "required": [ "version", "events" ], "additionalProperties": false }, "Receipt": { "type": "object", "properties": { "status": { "type": "string", "const": "accepted" }, "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "status", "requestId" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "error", "message", "requestId" ] } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-localisync-session" }, "diagnosticKey": { "type": "http", "scheme": "bearer", "description": "A dedicated distribution/channel diagnostic key. Cannot read translations or manage resources." } } } }