{ "openapi": "3.0.3", "info": { "title": "DevSpeak API v1", "version": "1.0.0", "description": "Machine-readable contract for the DevSpeak /api/v1 surface. This snapshot is synchronized to docs/internal/api-v1-inventory.md and marks orphaned or deprecated routes explicitly." }, "servers": [ { "url": "https://www.devspeak.dev", "description": "Production" } ], "tags": [ { "name": "Health" }, { "name": "Auth" }, { "name": "History" }, { "name": "Translation" }, { "name": "Provider Configuration" }, { "name": "Desktop Companion" }, { "name": "Legacy" } ], "paths": { "/api/v1/health": { "get": { "tags": ["Health"], "operationId": "getHealth", "summary": "Get API health", "description": "Public health check returning service status, API version, and timestamp.", "responses": { "200": { "description": "Health payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/v1/me": { "get": { "tags": ["Auth"], "operationId": "getCurrentIdentity", "summary": "Get caller identity and plan access", "description": "Resolves the authenticated caller's user ID, tier, features, limits, and current usage.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Identity and plan payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/auth/confirm": { "get": { "tags": ["Auth"], "operationId": "confirmAuthSession", "summary": "Confirm active session", "description": "Validates that the supplied API key or Firebase-authenticated session maps to an active user.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Active session confirmation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthConfirmResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/auth/session-key": { "post": { "tags": ["Auth"], "operationId": "createSessionKey", "summary": "Exchange Firebase auth for a session key", "description": "Creates an ephemeral dsk_sess_ API key from a Firebase Bearer token. The response is returned once and expires after 24 hours.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionKeyRequest" } } } }, "responses": { "201": { "description": "Ephemeral session key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionKeyResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/history": { "get": { "tags": ["History"], "operationId": "getTranslationHistory", "summary": "Get translation history", "description": "Returns paginated translation history for the authenticated caller.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "required": false, "description": "Page size. The server clamps values into the 1..200 range." }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "Zero-based pagination offset." } ], "responses": { "200": { "description": "Paginated translation history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/translate": { "post": { "tags": ["Translation"], "operationId": "translateText", "summary": "Run Stage 2 translation", "description": "Transforms input into an audience-specific technical document. Requires the optimize:write scope and the apiAccess feature.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslateRequest" } } } }, "responses": { "200": { "description": "Generated translation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/optimize": { "post": { "tags": ["Translation"], "operationId": "optimizeInput", "summary": "Run Stage 1 optimization", "description": "Returns the input improved in the language it was written in. By default it improves the whole text (word choice, flow, clarity, sentence structure) while keeping meaning, voice, facts, code and line breaks; correctionsOnly: true fixes spelling, grammar and punctuation only. Task-context-free: attachments, per-request custom instructions, and context project grounding are not supported and are silently dropped. Requires the optimize:write scope.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizeRequest" } } } }, "responses": { "200": { "description": "Optimized text", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/refine": { "post": { "tags": ["Translation"], "operationId": "refineTranslation", "summary": "Run Stage 3 refinement", "description": "Refines a previous output using targeted feedback. Requires the optimize:write scope and the iterativeRefinement feature.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefineRequest" } } } }, "responses": { "200": { "description": "Refined document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/user/config/providers/current": { "get": { "tags": ["Provider Configuration"], "operationId": "getProviderConfiguration", "summary": "Get active provider configuration", "description": "Loads the caller's active BYOK configuration. Requires Firebase auth and the customProvider feature.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current provider configuration or null", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderCurrentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "tags": ["Provider Configuration"], "operationId": "deleteProviderConfiguration", "summary": "Clear active provider configuration", "description": "Disables the active BYOK configuration. Requires Firebase auth and the customProvider feature.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Provider cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NullSuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/user/config/providers/test": { "post": { "tags": ["Provider Configuration"], "operationId": "testProviderConfiguration", "summary": "Test provider draft", "description": "Validates a provider draft without persisting changes. Requires Firebase auth and the customProvider feature.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConfigRequest" } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConfigurationEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/user/config/providers": { "post": { "tags": ["Provider Configuration"], "operationId": "saveProviderConfiguration", "summary": "Save provider configuration", "description": "Validates and persists a BYOK configuration. Requires Firebase auth and the customProvider feature.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConfigRequest" } } } }, "responses": { "200": { "description": "Provider configuration saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConfigurationEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ProviderValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/api/v1/desktop/session": { "post": { "tags": ["Desktop Companion"], "operationId": "createDesktopSession", "summary": "Create desktop session", "description": "Creates or refreshes a desktop session token. Requires Firebase auth.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopSessionCreateRequest" } } } }, "responses": { "201": { "description": "Desktop session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopSessionResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/desktop/projects": { "get": { "tags": ["Desktop Companion"], "operationId": "listDesktopProjects", "summary": "List desktop projects", "description": "Lists registered desktop projects for the caller's desktop session. Requires the desktop:projects:read scope.", "security": [ { "DesktopSessionAuth": [] } ], "responses": { "200": { "description": "Registered desktop projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopProjectsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": ["Desktop Companion"], "operationId": "upsertDesktopProject", "summary": "Create or update a desktop project", "description": "Registers or updates a desktop project and emits a sync event. Requires the desktop:projects:write scope.", "security": [ { "DesktopSessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopProjectUpsertRequest" } } } }, "responses": { "201": { "description": "Desktop project upserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopProjectEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/desktop/projects/sync": { "post": { "tags": ["Desktop Companion"], "operationId": "syncDesktopManifest", "summary": "Reconcile desktop file manifest", "description": "Compares a client-generated SHA-256 manifest against server state. Requires the desktop:projects:write scope.", "security": [ { "DesktopSessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectSyncRequest" } } } }, "responses": { "200": { "description": "Manifest delta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManifestDeltaResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/desktop/context/inject": { "post": { "tags": ["Desktop Companion"], "operationId": "injectDesktopContext", "summary": "Assemble workspace context", "description": "Builds a compact workspaceContext string from local file chunks. Requires the desktop:projects:write scope.", "security": [ { "DesktopSessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextInjectRequest" } } } }, "responses": { "200": { "description": "Assembled context", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssembledContextResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/desktop/sync": { "get": { "tags": ["Desktop Companion", "Legacy"], "operationId": "listDesktopSyncEvents", "summary": "Poll desktop sync events", "description": "Legacy polling endpoint for desktop sync events. The inventory marks this route as orphaned and it should not be used for new clients.", "deprecated": true, "security": [ { "DesktopSessionAuth": [] } ], "parameters": [ { "in": "query", "name": "projectId", "required": true, "schema": { "$ref": "#/components/schemas/DesktopIdentifier" } }, { "in": "query", "name": "after", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Legacy sync event page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DesktopSyncResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v1/optimize-input": { "post": { "tags": ["Legacy"], "operationId": "redirectOptimizeInput", "summary": "Deprecated optimize-input redirect", "description": "Backward-compatibility redirect from the pre-refactor optimize-input path to /api/v1/optimize. Sunset: 2026-10-01.", "deprecated": true, "responses": { "308": { "description": "Permanent redirect to /api/v1/optimize" } } } }, "/api/v1/user/config/keys": { "post": { "tags": ["Legacy"], "operationId": "legacyUpsertProviderKey", "summary": "Legacy BYOK upsert", "description": "Deprecated legacy BYOK route retained for older macOS clients. The inventory flags this route as a security concern because it bypasses the customProvider entitlement gate.", "deprecated": true, "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyCredentialRequest" } } } }, "responses": { "200": { "description": "Legacy provider response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderConfigurationEnvelope" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ProviderValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "DevSpeak API key. Supported prefixes include dsk_live_, dsk_test_, and dsk_sess_." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Firebase ID token", "description": "Firebase Bearer token used for user-authenticated routes." }, "DesktopSessionAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Desktop session token", "description": "Desktop companion bearer token returned by POST /api/v1/desktop/session." } }, "responses": { "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Missing scope, feature, or plan access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ProviderValidationFailed": { "description": "Provider validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "GatewayTimeout": { "description": "Upstream timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ProviderConfigurationUnavailable": { "description": "No BYOK provider is currently configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "Audience": { "type": "string", "enum": [ "Junior Dev", "Senior Dev", "Tech Lead", "SRE", "Data Engineer" ] }, "Context": { "type": "string", "enum": ["Backend", "Frontend", "Mobile", "Data/ML", "DevOps"] }, "Format": { "type": "string", "enum": [ "Technical Spec", "Jira Tickets", "API Design", "RFC", "Data Model", "Prompt", "Optimize" ] }, "ApiScope": { "type": "string", "enum": ["optimize:write", "translate:write", "history:read"] }, "ProviderType": { "type": "string", "enum": ["gemini", "openai", "anthropic", "openai-compatible"] }, "DesktopSessionScope": { "type": "string", "enum": [ "desktop:projects:read", "desktop:projects:write", "desktop:sync:read" ] }, "DesktopIdentifier": { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "ErrorResponse": { "type": "object", "required": ["success", "error"], "properties": { "success": { "type": "boolean", "enum": [false] }, "error": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "code": { "type": "string" }, "quotaKey": { "type": "string" }, "currentUsage": { "type": "integer" }, "limit": { "type": "integer" } }, "additionalProperties": true }, "NullSuccessResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "nullable": true, "description": "Always null.", "additionalProperties": false, "example": null } } }, "HealthResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": ["status", "version", "timestamp"], "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "v1" }, "timestamp": { "type": "string", "format": "date-time" } } } } }, "MeResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": [ "userId", "tier", "features", "limits", "usage", "quotas" ], "properties": { "userId": { "type": "string" }, "tier": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": { "type": "integer" } }, "usage": { "type": "object", "required": ["refinementCount", "currentPeriod"], "properties": { "refinementCount": { "type": "integer" }, "currentPeriod": { "type": "string" } } }, "quotas": { "type": "object", "required": [ "managedTokens", "apiKeys", "managedTokensUnlimited", "apiKeysUnlimited" ], "properties": { "managedTokens": { "type": "integer" }, "apiKeys": { "type": "integer" }, "managedTokensUnlimited": { "type": "boolean" }, "apiKeysUnlimited": { "type": "boolean" } } } } } } }, "AuthConfirmResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": ["userId", "confirmed"], "properties": { "userId": { "type": "string" }, "confirmed": { "type": "boolean", "enum": [true] } } } } }, "SessionKeyRequest": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiScope" }, "minItems": 1, "default": ["optimize:write"] }, "label": { "type": "string", "maxLength": 100 } } }, "SessionKeyResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": ["key", "expiresAt", "scopes"], "properties": { "key": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiScope" } } } } } }, "HistoryItem": { "type": "object", "required": [ "id", "inputText", "output", "audience", "context", "format", "tone", "wordCount", "latencyMs", "createdAt" ], "properties": { "id": { "type": "string" }, "inputText": { "type": "string" }, "output": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "context": { "$ref": "#/components/schemas/Context" }, "format": { "$ref": "#/components/schemas/Format" }, "tone": { "type": "integer", "minimum": 0, "maximum": 100 }, "wordCount": { "type": "integer" }, "latencyMs": { "type": "integer" }, "model": { "type": "string" }, "provider": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "HistoryResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": ["items", "offset", "limit"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryItem" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "TranslateRequest": { "type": "object", "required": ["input", "audience", "context", "format", "tone"], "properties": { "input": { "type": "string", "minLength": 10, "maxLength": 10000 }, "audience": { "$ref": "#/components/schemas/Audience" }, "context": { "$ref": "#/components/schemas/Context" }, "format": { "$ref": "#/components/schemas/Format" }, "tone": { "type": "integer", "minimum": 0, "maximum": 100 }, "customInstructions": { "type": "string", "maxLength": 10000 }, "workspaceContext": { "type": "string", "maxLength": 5000 }, "translationId": { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9_-]+$" }, "correctionsOnly": { "type": "boolean", "default": false, "description": "Only with format \"Optimize\", which returns the input improved in its own language instead of a document. true fixes spelling, grammar and punctuation only." } } }, "OptimizeRequest": { "type": "object", "required": ["input", "audience", "context"], "description": "Stage 1 contract. Task-level context fields (attachments, customInstructions, contextProjectId) are dropped at the route boundary.", "properties": { "input": { "type": "string", "minLength": 10, "maxLength": 10000 }, "audience": { "$ref": "#/components/schemas/Audience" }, "context": { "$ref": "#/components/schemas/Context" }, "managedModel": { "type": "string", "description": "Allowlisted managed model pin. Omit to use the fast Stage 1 default." }, "translationId": { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9_-]+$" }, "correctionsOnly": { "type": "boolean", "default": false, "description": "Write mode. false (default) improves the whole text in its own language (word choice, flow, clarity, sentence structure); true fixes spelling, grammar and punctuation only." } } }, "RefineRequest": { "type": "object", "required": [ "previousOutput", "feedback", "audience", "context", "format", "tone", "originalInput" ], "properties": { "originalInput": { "type": "string", "maxLength": 10000, "default": "" }, "previousOutput": { "type": "string", "minLength": 1, "maxLength": 50000 }, "feedback": { "type": "string", "minLength": 1, "maxLength": 5000 }, "audience": { "$ref": "#/components/schemas/Audience" }, "context": { "$ref": "#/components/schemas/Context" }, "format": { "$ref": "#/components/schemas/Format" }, "tone": { "type": "integer", "minimum": 0, "maximum": 100 }, "workspaceContext": { "type": "string", "maxLength": 5000 }, "translationId": { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9_-]+$" } } }, "TranslationMetadata": { "type": "object", "required": ["wordCount", "latencyMs", "model"], "properties": { "wordCount": { "type": "integer" }, "latencyMs": { "type": "integer" }, "model": { "type": "string" }, "provider": { "type": "string" }, "credentialSource": { "type": "string" }, "endpointHost": { "type": "string", "nullable": true }, "isOutOfScope": { "type": "boolean" }, "inputTokens": { "type": "integer", "nullable": true }, "outputTokens": { "type": "integer", "nullable": true }, "thinkingTokens": { "type": "integer", "nullable": true } } }, "TranslationResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": ["output", "metadata"], "properties": { "output": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/TranslationMetadata" } } } } }, "ProviderConfiguration": { "type": "object", "required": [ "providerType", "providerName", "apiEndpoint", "metadata", "enabled", "updatedAt", "lastValidatedAt", "status", "validationMessage" ], "properties": { "providerType": { "$ref": "#/components/schemas/ProviderType" }, "providerName": { "type": "string" }, "apiEndpoint": { "type": "string", "nullable": true }, "metadata": { "type": "object", "required": ["model", "label", "keyPreview", "endpointHost"], "properties": { "model": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "keyPreview": { "type": "string", "nullable": true }, "endpointHost": { "type": "string", "nullable": true } } }, "enabled": { "type": "boolean" }, "updatedAt": { "type": "string", "nullable": true }, "lastValidatedAt": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["unconfigured", "invalid", "active"] }, "validationMessage": { "type": "string", "nullable": true } } }, "ProviderCurrentResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "allOf": [ { "$ref": "#/components/schemas/ProviderConfiguration" } ], "nullable": true }, "configured": { "type": "boolean" } } }, "ProviderConfigurationEnvelope": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "$ref": "#/components/schemas/ProviderConfiguration" } } }, "ProviderConfigRequest": { "type": "object", "required": ["providerType", "providerName"], "properties": { "providerType": { "$ref": "#/components/schemas/ProviderType" }, "providerName": { "type": "string", "minLength": 1, "maxLength": 100 }, "apiKey": { "type": "string", "maxLength": 500 }, "isExistingKey": { "type": "boolean" }, "baseURL": { "type": "string", "format": "uri" }, "modelIdentifier": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "LegacyCredentialRequest": { "type": "object", "required": ["providerType", "apiKey"], "properties": { "providerType": { "$ref": "#/components/schemas/ProviderType" }, "apiKey": { "type": "string", "minLength": 1, "maxLength": 500 }, "apiEndpoint": { "type": "string", "format": "uri" }, "model": { "type": "string", "minLength": 1, "maxLength": 120 }, "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "additionalProperties": false }, "DesktopDevice": { "type": "object", "required": [ "deviceId", "deviceLabel", "platform", "runtime", "lastSeenAt" ], "properties": { "deviceId": { "$ref": "#/components/schemas/DesktopIdentifier" }, "deviceLabel": { "type": "string" }, "platform": { "type": "string", "enum": ["desktop-app"] }, "runtime": { "type": "string", "enum": ["electron", "tauri", "unknown"] }, "lastSeenAt": { "type": "string", "format": "date-time" } } }, "DesktopSessionCreateRequest": { "type": "object", "required": ["deviceId", "deviceLabel"], "properties": { "deviceId": { "$ref": "#/components/schemas/DesktopIdentifier" }, "deviceLabel": { "type": "string", "minLength": 1, "maxLength": 120 }, "runtime": { "type": "string", "enum": ["electron", "tauri", "unknown"], "default": "unknown" } }, "additionalProperties": false }, "DesktopSessionResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": ["token", "expiresInSeconds", "scopes", "device"], "properties": { "token": { "type": "string" }, "expiresInSeconds": { "type": "integer" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopSessionScope" } }, "device": { "$ref": "#/components/schemas/DesktopDevice" } } } } }, "DesktopProject": { "type": "object", "required": [ "projectId", "name", "rootPath", "createdAt", "updatedAt", "lastSyncedAt", "lastSyncedByDeviceId" ], "properties": { "projectId": { "$ref": "#/components/schemas/DesktopIdentifier" }, "name": { "type": "string" }, "rootPath": { "type": "string", "maxLength": 2048 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lastSyncedAt": { "type": "string", "format": "date-time" }, "lastSyncedByDeviceId": { "$ref": "#/components/schemas/DesktopIdentifier" } } }, "DesktopProjectsResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopProject" } } } }, "DesktopProjectEnvelope": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "$ref": "#/components/schemas/DesktopProject" } } }, "DesktopProjectUpsertRequest": { "type": "object", "required": ["projectId", "name", "rootPath"], "properties": { "projectId": { "$ref": "#/components/schemas/DesktopIdentifier" }, "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "rootPath": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "additionalProperties": false }, "ProjectSyncFile": { "type": "object", "required": ["path", "hash"], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 1024 }, "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 50000000 }, "modifiedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ProjectSyncRequest": { "type": "object", "required": ["projectId", "files"], "properties": { "projectId": { "$ref": "#/components/schemas/DesktopIdentifier" }, "files": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/components/schemas/ProjectSyncFile" } } }, "additionalProperties": false }, "ManifestDelta": { "type": "object", "required": [ "manifestId", "toUpload", "toDelete", "unchanged", "totalFiles" ], "properties": { "manifestId": { "type": "string" }, "toUpload": { "type": "array", "items": { "type": "string" } }, "toDelete": { "type": "array", "items": { "type": "string" } }, "unchanged": { "type": "array", "items": { "type": "string" } }, "totalFiles": { "type": "integer" } } }, "ManifestDeltaResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "$ref": "#/components/schemas/ManifestDelta" } } }, "ContextChunk": { "type": "object", "required": ["path", "content"], "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 1024 }, "content": { "type": "string", "maxLength": 8192 }, "symbols": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 200 } } }, "additionalProperties": false }, "ContextInjectRequest": { "type": "object", "required": ["projectId", "chunks"], "properties": { "projectId": { "$ref": "#/components/schemas/DesktopIdentifier" }, "label": { "type": "string", "maxLength": 200 }, "query": { "type": "string", "maxLength": 32000, "description": "Pending translation input. Chunks are ranked against it so query-relevant files survive the context budget instead of whichever files were enumerated first." }, "chunks": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/ContextChunk" } } }, "additionalProperties": false }, "AssembledContext": { "type": "object", "required": ["contextId", "contextText", "tokenEstimate", "chunkCount"], "properties": { "contextId": { "type": "string" }, "contextText": { "type": "string" }, "tokenEstimate": { "type": "integer" }, "chunkCount": { "type": "integer" }, "includedCount": { "type": "integer", "description": "Chunks that fit the context budget. Below chunkCount means context was dropped." } } }, "AssembledContextResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "$ref": "#/components/schemas/AssembledContext" } } }, "DesktopSyncEvent": { "type": "object", "required": ["eventId", "eventType", "userId", "occurredAt", "source"], "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string" }, "userId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": ["api-v1", "web", "desktop"] }, "deviceId": { "type": "string" }, "projectId": { "type": "string" }, "entityType": { "type": "string", "enum": ["translation", "project", "manifest"] }, "entityId": { "type": "string" }, "summary": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true } } }, "DesktopSyncResponse": { "type": "object", "required": ["success", "data"], "properties": { "success": { "type": "boolean", "enum": [true] }, "data": { "type": "object", "required": ["items", "nextCursor", "serverTime"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DesktopSyncEvent" } }, "nextCursor": { "type": "string", "nullable": true }, "serverTime": { "type": "string", "format": "date-time" } } } } }, "OptimizeResponse": { "type": "object", "required": ["output", "metadata"], "properties": { "output": { "type": "string" }, "metadata": { "type": "object", "required": [ "wordCount", "latencyMs", "model", "provider", "credentialSource" ], "properties": { "wordCount": { "type": "integer" }, "latencyMs": { "type": "integer" }, "model": { "type": "string" }, "provider": { "type": "string" }, "credentialSource": { "type": "string" }, "endpointHost": { "type": "string", "nullable": true }, "inputTokens": { "type": "integer", "nullable": true }, "outputTokens": { "type": "integer", "nullable": true }, "thinkingTokens": { "type": "integer", "nullable": true } } } } }, "UserLlmCredentialRequest": { "type": "object", "required": ["providerType", "apiKey"], "properties": { "providerType": { "$ref": "#/components/schemas/ProviderType" }, "apiKey": { "type": "string", "minLength": 1 }, "baseUrl": { "type": "string", "nullable": true }, "providerName": { "type": "string", "nullable": true }, "isExistingKey": { "type": "boolean" } } }, "BYOKConnectionStatus": { "type": "string", "enum": ["active", "invalid", "unconfigured", "validating"] }, "CurrentProviderEnvelope": { "type": "object", "required": ["configured"], "properties": { "configured": { "type": "boolean", "nullable": true }, "provider": { "$ref": "#/components/schemas/ProviderConfiguration", "nullable": true } } } } } }